Authentication

One organization key authenticates inference on /v1 and the management API on /api.

The key

A key is xpl_ plus 40 lowercase hex characters and belongs to exactly one organization. The secret is shown once, at creation on the API keys page. GET /api/whoami tells you which organization a key belongs to; most /api/orgs/{org_id}/... routes need that org_id.

GET/api/whoami
curl https://api.experientiallabs.ai/api/whoami \
  -H "Authorization: Bearer YOUR_API_KEY"

Headers per protocol

Send exactly one credential header.

SurfaceHeader
OpenAI routes (/v1/*), management (/api/*)Authorization: Bearer YOUR_API_KEY
Anthropic Messages (/v1/messages)x-api-key or Authorization: Bearer; x-api-key wins if both are sent
Gemini (/v1beta/*)x-goog-api-key (SDK default), ?key=, or Authorization: Bearer

The catalog reads (GET /api/models*) need no key; with a key they add your organization's own models. /v1 and /api/v1 answer CORS for any origin without credentials, so keep keys server-side on pages you do not control.

GET/v1/models
curl https://api.experientiallabs.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Inference and provisioning keys

Both are xpl_ keys; provisioning is a flag set at creation. Only an org admin can create the first provisioning key (in the dashboard).

CanInference keyProvisioning key
Call models, read catalog, usage, request logyesyes
Connect BYOK keys, set data controls, edit waterfallsyesyes
Create, update, revoke keys (/api/v1/keys)no (403)yes
Identities, budgets, Spend reports, usage/by-keyno (403)yes
POST/api/v1/keysGET/api/v1/keys
curl https://api.experientiallabs.ai/api/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer-42", "limit": 25}'
# -> {"data": {...,"hash": "<id>"}, "key": "xpl_..."}  (plaintext returned once)
# limit: USD cap per limit_reset window (daily default). DELETE /api/v1/keys/{hash} revokes.

Key limits

A key can carry a spend cap (daily, weekly, monthly or yearly, UTC) and request or token rate limits, set by an admin under Budget & limits on the API keys page. Read them back with the key.

GET/api/v1/keyGET/api/gateway/keys/{api_key_id}/limits
curl https://api.experientiallabs.ai/api/v1/key \
  -H "Authorization: Bearer YOUR_API_KEY"
# usage, limit, limit_remaining (in the cap's own window)

When auth fails

A missing, malformed, expired or revoked key gets the same 401 on /v1 (code: invalid_key); /api answers 401 {"error": "Unauthorized"}. Fix the header; retrying fails the same way. /v1/messages and /v1beta use their own envelopes. See Errors.

{
  "error": {
    "message": "A valid gateway Bearer key is required. Send the virtual key as 'Authorization: Bearer <key>'.",
    "type": "authentication_error",
    "code": "invalid_key",
    "param": null
  }
}