Authentication & management keys

Two gates enable access: the deployment switch and tenant opt-in. Every management key belongs to exactly one tenant; one tenant can have multiple keys for independent automation clients.

Request authentication

Authorization: Bearer <management-key>

The key establishes the tenant. Caller-supplied tenant headers cannot expand that scope. Gateway inference keys, log-export credentials and management keys are not interchangeable.

Credential	Purpose	Secret retrieval
Management key	Read/write authorized tenant configuration.	Issuance only; cannot reveal it later.
Gateway app key	Runtime access to one canonical gateway app.	Explicit reveal with `credentials:read`.
Verified administrator identity	Opt in a tenant; create, change or revoke management keys.	Follows the administration identity provider.

Enablement and lifecycle

Enable LLMGATEWAY_MANAGEMENT_API_ENABLED on the central service. It defaults to false.
An authorized administrator enables management for the tenant.
The administrator creates a named key with explicit scopes and, optionally, an expiry.
Store the returned secret. Issue a replacement key before revoking a key used by an existing integration.

Disabling tenant management suspends its keys. Re-enabling restores keys that remain unexpired and unrevoked. This does not enable/disable gateway apps. Tenant admins may continue to inspect enablement and revoke keys while tenant management is suspended, provided the deployment gate is enabled.

Management keys do not expire by default. expires_at is a future RFC 3339 timestamp or null. On PATCH, omission preserves the current expiry and null clears it. Expired and revoked keys are terminal: issue a new key instead of resurrecting one.

Scopes

All scopes listed for an operation are required. No scope implies another.

Scope	Grants
`read`	Configuration, catalogs, prompts, key metadata, config history, policy reads, offline validation/simulation.
`config:write`	App create/update/enable/disable, provider attachments/conversion, app controls, prompt changes and eligible app rollback.
`providers:write`	Shared-provider create/update/enable/disable, credential rotation and explicit upstream tests.
`policy:write`	Create and edit policy drafts.
`policy:publish`	Publish and roll back policy revisions; enable/disable tenant-wide authority.
`credentials:write`	Issue/revoke gateway app keys and change supported expiry.
`credentials:read`	Explicitly reveal a retained gateway app credential.

App creation requires both config:write and credentials:write because it issues an initial gateway credential. Attaching an existing provider needs config:write; changing that shared provider needs providers:write.

Administration boundary

The following routes use the separate /llmgateway/management-admin/v1 prefix. They require a verified tenant administrator for that tenant or an authorized Quilr operator. A management key cannot grant itself more permissions or enable its tenant.

Administrator credentials must identify a verified tenant administrator or authorized Quilr operator. Use the administration identity provider configured for your deployment; tenant headers alone do not authorize administrative access.

GET/admin/tenants/{tenant_id}/settings

Read tenant management settings

Administrator-only bootstrap. Verify tenant membership and admin role or authorized Quilr operator identity.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 1

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/settings' \
  --header 'Authorization: Bearer <verified-admin-token>'

Authentication, errors & retry rules

PATCH/admin/tenants/{tenant_id}/settings

Enable or suspend tenant management

Requires the deployment switch and verified administrator authority. Disable suspends keys without revoking them or changing gateway apps.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 2

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Full request body specification application/json

enabledbooleanrequired

Enable management for this tenant. Disabling suspends existing keys without revocation.

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/settings' \
  --header 'Authorization: Bearer <verified-admin-token>' \
  --header 'If-Match: "resource-version"' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": true
}'

Authentication, errors & retry rules

GET/admin/tenants/{tenant_id}/keys

List management keys

List metadata only. Existing management secrets cannot be retrieved.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 3

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

limit (query)integeroptional

Items per page.

min: 1max: 200default: 50

cursor (query)stringoptional

Opaque cursor returned by this same collection and filters.

No request body.

curl --request GET \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/keys?limit=50' \
  --header 'Authorization: Bearer <verified-admin-token>'

Authentication, errors & retry rules

POST/admin/tenants/{tenant_id}/keys

Issue a management key

Issue a tenant-bound key through verified administration. Tenant opt-in must be enabled. Secret is available at issuance only; no expiry by default.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 2

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

Idempotency-Key (header)stringrequired

Unique operation key. Reuse only with the identical request; mismatch returns 409.

min length: 1max length: 128

Full request body specification application/json

namestringrequired

Human-readable automation name.

min length: 1max length: 120

scopesarray<string>required

Explicit scopes; there are no implicit scope grants.

min items: 1unique items

Array item specification

string

Values: "read""config:write""providers:write""policy:write""policy:publish""credentials:write""credentials:read"

expires_atstring | nulloptional

Omit on create or send null for no expiry. On PATCH, omission preserves the current expiry and null removes it. Expired/revoked credentials cannot be resurrected.

Variant 1 string

string

Future RFC 3339 timestamp with an explicit timezone.

format: date-time

Also accepts null.

Unknown fields are rejected in this object.

curl --request POST \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/keys' \
  --header 'Authorization: Bearer <verified-admin-token>' \
  --header 'Idempotency-Key: operation-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Deployment automation",
  "scopes": [
    "read",
    "config:write",
    "providers:write",
    "credentials:write"
  ],
  "expires_at": null
}'

Authentication, errors & retry rules

PATCH/admin/tenants/{tenant_id}/keys/{key_id}

Update a management key

Change name, explicit scopes or optional expiry. Expired/revoked keys cannot be reactivated; secret is not returned.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 3

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

key_id (path)stringrequired

min length: 1

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

Full request body specification application/json

namestringoptional

Optional new display name.

min length: 1max length: 120

scopesarray<string>optional

Explicit scopes; there are no implicit scope grants.

min items: 1unique items

Array item specification

string

Values: "read""config:write""providers:write""policy:write""policy:publish""credentials:write""credentials:read"

expires_atstring | nulloptional

Omit on create or send null for no expiry. On PATCH, omission preserves the current expiry and null removes it. Expired/revoked credentials cannot be resurrected.

Variant 1 string

string

Future RFC 3339 timestamp with an explicit timezone.

format: date-time

Also accepts null.

Unknown fields are rejected in this object.

curl --request PATCH \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/keys/key_example' \
  --header 'Authorization: Bearer <verified-admin-token>' \
  --header 'If-Match: "resource-version"' \
  --header 'Content-Type: application/json' \
  --data '{
  "scopes": [
    "read"
  ],
  "expires_at": null
}'

Authentication, errors & retry rules

DELETE/admin/tenants/{tenant_id}/keys/{key_id}

Revoke a management key

Idempotently revoke a key. This remains available to authorized administrators while tenant management is suspended.

REQUIRESVerified tenant admin / Quilr operator

Path, query & header parameters 3

tenant_id (path)stringrequired

Verified administrator tenant scope.

min length: 1

key_id (path)stringrequired

min length: 1

If-Match (header)stringrequired

Exact quoted ETag from a current resource read.

No request body.

curl --request DELETE \
  'https://management.example.com/llmgateway/management-admin/v1/tenants/tenant_example/keys/key_example' \
  --header 'Authorization: Bearer <verified-admin-token>' \
  --header 'If-Match: "resource-version"'

Authentication, errors & retry rules

Request authentication​

Enablement and lifecycle​

Scopes​

Administration boundary​

Request authentication

Enablement and lifecycle

Scopes

Administration boundary