Skip to content

Admin API

Admin endpoints manage tenants, API keys, namespaces, and usage. All admin endpoints require the engine service key (HX_GATE_ENGINE_SERVICE_KEY) passed via Authorization: Bearer.

Create tenant

Provision a new tenant with an API key and namespace ACL.

POST /gate/onboard/create

Request body

Field Type Required Description
tenant_id string Yes Unique tenant identifier
plan string No Billing tier: starter, builder, pro, enterprise (default: starter)
namespaces list[string] No Allowed namespaces (default: ["default"])
email string No Tenant contact email

Example

curl -X POST https://gate.holonomx.com/gate/onboard/create \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme-corp",
    "plan": "builder",
    "namespaces": ["default", "staging", "production"],
    "email": "admin@acme.com"
  }'

Response — 201 Created

{
  "tenant_id": "acme-corp",
  "api_key": "hx_live_a1b2c3d4e5f6...",
  "plan": "builder",
  "namespaces": ["default", "staging", "production"],
  "monthly_quota": 50000,
  "rate_limit": {"requests": 100, "window_s": 60}
}

Warning

The api_key is shown once. Store it securely — it cannot be recovered.

Rotate API key

Invalidate the current key and issue a new one. The old key stops working immediately.

POST /gate/onboard/rotate-key

Request body

Field Type Required Description
tenant_id string Yes Target tenant

Response — 200 OK

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

Add namespace

Grant a tenant access to an additional namespace.

POST /gate/onboard/add-namespace

Request body

Field Type Required Description
tenant_id string Yes Target tenant
namespace string Yes Namespace to add

Response — 200 OK

{
  "tenant_id": "acme-corp",
  "namespaces": ["default", "staging", "production", "analytics"]
}

Update tier

Change a tenant's billing tier and quota.

POST /gate/onboard/update-tier

Request body

Field Type Required Description
tenant_id string Yes Target tenant
plan string Yes New tier: starter, builder, pro, enterprise

Response — 200 OK

{
  "tenant_id": "acme-corp",
  "plan": "pro",
  "monthly_quota": 500000,
  "rate_limit": {"requests": 1000, "window_s": 60}
}

Deactivate tenant

Soft-delete a tenant. API key is immediately invalidated. Data is retained for the compaction retention period.

POST /gate/onboard/deactivate

Request body

Field Type Required Description
tenant_id string Yes Target tenant

Response — 200 OK

{
  "tenant_id": "acme-corp",
  "status": "deactivated"
}

List tenants

Return all registered tenants with their current plans and namespace ACLs.

GET /gate/admin/tenants

Response — 200 OK

{
  "tenants": [
    {
      "tenant_id": "acme-corp",
      "plan": "pro",
      "namespaces": ["default", "staging", "production"],
      "active": true
    }
  ]
}

Get usage — all tenants

GET /gate/admin/usage

Response — 200 OK

{
  "period": "2026-01",
  "tenants": [
    {
      "tenant_id": "acme-corp",
      "cus_used": 12450.5,
      "monthly_quota": 500000,
      "utilization": 0.0249
    }
  ]
}

Get usage — single tenant

GET /gate/admin/usage/{tenant_id}

Response — 200 OK

{
  "tenant_id": "acme-corp",
  "period": "2026-01",
  "cus_used": 12450.5,
  "monthly_quota": 500000,
  "utilization": 0.0249,
  "breakdown": {
    "put": 5000.0,
    "get": 250.0,
    "query_topk": 3200.0,
    "serve": 2000.0,
    "search": 1500.0,
    "delete": 500.5
  }
}

Reload tenant registry

Hot-reload the tenant registry from disk without restarting the gate process.

POST /gate/admin/reload

Response — 200 OK

{
  "status": "ok",
  "tenants_loaded": 42
}

Health check

GET /health
GET /gate/health

Response — 200 OK

{
  "status": "ok",
  "engine_reachable": true,
  "redis_connected": true,
  "uptime_s": 86400
}

No authentication required.