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.
/api/whoamicurl https://api.experientiallabs.ai/api/whoami \
-H "Authorization: Bearer YOUR_API_KEY"Headers per protocol
Send exactly one credential header.
| Surface | Header |
|---|---|
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.
/v1/modelscurl 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).
| Can | Inference key | Provisioning key |
|---|---|---|
| Call models, read catalog, usage, request log | yes | yes |
| Connect BYOK keys, set data controls, edit waterfalls | yes | yes |
Create, update, revoke keys (/api/v1/keys) | no (403) | yes |
Identities, budgets, Spend reports, usage/by-key | no (403) | yes |
/api/v1/keysGET/api/v1/keyscurl 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}/limitscurl 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
}
}