Skip to main content
Every management API request carries a bearer token:

​
Two kinds of key

The management API rejects proxy keys with 401 Invalid API key; the runtime rejects organization keys. Use the proxy key in your application’s base_url client and the organization key in scripts, CI and integrations that call this API. Dashboard users authenticate with their sign-in session instead of a key. Some endpoints are only available to a signed-in user; see Human-only endpoints.

​
Scopes

An organization key is created with one of two scopes: A read key calling a mutating endpoint receives:
The scope is fixed at creation. To change it, create a new key and revoke the old one.

​
Human-only endpoints

These endpoints require a signed-in dashboard session and return 403 for any organization key, because they manage credentials, membership or billing:
  • Proxy API keys: GET/POST /proxies/{proxy_id}/keys, DELETE /proxies/{proxy_id}/keys/{key}
  • Organization API keys: GET/POST /orgs/{org_id}/keys, DELETE /orgs/{org_id}/keys/{key} (admins)
  • Organization and members: GET/PATCH /orgs/{org_id}, /orgs/{org_id}/users/... (writes require an admin)
  • Alert rule writes and notification settings: POST/PATCH/DELETE /alert-rules, PATCH /notification-settings, POST /notification-settings/test (admins)
  • Hybrid deployments: everything under /deployments (admins, except GET /deployments/health)
Each endpoint page states which credential it accepts.

​
Creating an organization key

  1. In the dashboard, open Settings → API Keys and choose Create API key.
  2. Give it a label, an expiry (30, 60 or 90 days) and an access level (Read only or Read and write).
  3. Copy the secret. It is shown once; the list afterwards shows only the identifier (ak_…).
The same flow is available to admins as POST /orgs/{org_id}/keys.

​
Revocation

Deleting a key in the dashboard or via DELETE /orgs/{org_id}/keys/{key} takes effect immediately on every request. Keys revoked directly in Clerk, outside Xenovia, can remain valid for up to about 90 seconds while verification caches expire. Proxy keys are revoked from the proxy’s API keys tab; the runtime rejects a revoked key within seconds.

​
Authentication failures

​
Handling keys safely

  • Store keys in a secret manager and inject them at runtime; never commit them.
  • Use separate organizations or at least separate keys per environment.
  • Prefer read keys for reporting and dashboards; reserve write keys for provisioning.
  • Rotate before the expiry date: create the replacement, deploy it, then revoke the old key.
Never call the management API from a browser or mobile client. Organization keys grant access to every proxy, policy and trace in the organization.