Skip to content

Authentication

All data and query endpoints require a tenant API key. Admin endpoints require the service key.

API keys

API keys are issued during tenant onboarding (via the Console or Stripe checkout). Keys follow the format:

hx_live_<random_string>

Keys are SHA-256 hashed before storage. The plaintext key is shown once at creation and cannot be recovered. If lost, rotate via the Console or admin API.

Passing your key

Include the key in the X-Api-Key header:

curl -H "X-Api-Key: hx_live_abc123..." \
     https://gate.holonomx.com/v1/get/default/my-key

Or use Authorization: Bearer:

curl -H "Authorization: Bearer hx_live_abc123..." \
     https://gate.holonomx.com/v1/get/default/my-key

Both headers are accepted. If both are present, X-Api-Key takes precedence.

SDK configuration

# Option 1: Environment variable
# export HX_API_KEY=hx_live_abc123...
hx = HolonomiX(url="https://gate.holonomx.com")

# Option 2: Explicit
hx = HolonomiX(url="https://gate.holonomx.com", api_key="hx_live_abc123...")

const hx = new HolonomiXClient({
  baseUrl: "https://gate.holonomx.com",
  apiKey: "hx_live_abc123...",
});

client := holonomix.NewClient("https://gate.holonomx.com", "hx_live_abc123...")

Key rotation

Rotate a key without downtime:

curl -X POST https://gate.holonomx.com/gate/onboard/rotate-key \
     -H "Authorization: Bearer $SERVICE_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tenant_id": "acme-corp"}'

Response:

{
  "tenant_id": "acme-corp",
  "api_key": "hx_live_new_key_here..."
}

The old key is immediately invalidated. Update your application and redeploy.

Namespace isolation

Each API key is bound to a set of allowed namespaces. Requests to namespaces outside your ACL return 403 Forbidden.

{
  "detail": "Namespace 'staging' not permitted for tenant 'acme-corp'"
}

To add a namespace, contact your administrator or use the admin API:

curl -X POST https://gate.holonomx.com/gate/onboard/add-namespace \
     -H "Authorization: Bearer $SERVICE_KEY" \
     -H "Content-Type: application/json" \
     -d '{"tenant_id": "acme-corp", "namespace": "staging"}'

Admin authentication

Admin endpoints (/gate/admin/*, /gate/onboard/*) are authenticated with the engine service key, not tenant API keys. Pass it as Authorization: Bearer:

curl -H "Authorization: Bearer $HX_GATE_ENGINE_SERVICE_KEY" \
     https://gate.holonomx.com/gate/admin/tenants

Service key scope

The service key has full admin access to all tenants. Never expose it to client applications. Store it in environment variables or a secrets manager.