API Reference
Provider Keys
Adding, reading, changing, rotating, transferring and deleting provider keys with /v1/provider-keys.
The provider keys endpoints manage the credentials an organization uses to call model providers. Reading needs provider_keys:read, adding, changing, rotating and transferring need provider_keys:write, and deleting needs provider_keys:delete. Reads never return a secret. See Provider Key.
Endpoints
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/provider-keys | List provider keys, without secrets. Paginated. | provider_keys:read |
| POST | /v1/provider-keys | Add a key. Returns 201 with the secret once. Accepts dry_run and an Idempotency-Key. | provider_keys:write |
| GET | /v1/provider-keys/{id} | Get one key. | provider_keys:read |
| PATCH | /v1/provider-keys/{id} | Change name, description, enabled, is_default and provider settings. Accepts dry_run. | provider_keys:write |
| DELETE | /v1/provider-keys/{id} | Delete a disabled key that nothing uses. | provider_keys:delete |
| POST | /v1/provider-keys/{id}/rotate | Replace the secret, keeping the key id. Returns 200 with the secret once. | provider_keys:write |
| POST | /v1/provider-keys/{id}/transfer | Copy or move the key to another organization in the account. Requires an Idempotency-Key. | provider_keys:write; a move also provider_keys:delete |
Key fields
| Field | Type |
|---|---|
id | string |
The key id, prefixed llpk_, used in provider_key_id. | |
name | string, required on create |
| 1 to 80 characters. | |
description | string or null |
| Up to 2,000 characters. | |
provider | string, required on create |
| The provider id. Fixed. | |
secret | string, required on create and rotate |
| The credential. Never returned by reads. | |
enabled | boolean |
| Defaults to true. | |
is_default | boolean |
| Whether this is the provider's default key. Setting true moves the default from the previous key. | |
bedrock | object |
AWS Bedrock: region, auth_mode, access_key_id, and on create session_token. PATCH changes only region. | |
vertex | object |
Google Vertex: project_id and region. | |
openai | object |
OpenAI: data_residency, and on create organization. PATCH changes only data_residency. | |
custom | object |
Custom endpoints: base_url and api_format. Fixed after create. | |
key_prefix | string |
| The start of the secret, to recognize it. | |
etag | string |
| The quoted version, for If-Match. | |
The secret is in the response to the first successful create or rotate only; a dry run or an idempotent replay returns the key without it.
Transferring a key
POST /v1/provider-keys/{id}/transfer takes the destination organization_id, mode (copy or move), and an optional new name and description. Copy creates a new key in the destination. Move creates the destination key and deletes the source in one step, and refuses a default key or one that routers or model groups use. A transfer needs a key of the account organization whose creator is an admin of both organizations, requires an Idempotency-Key, has no dry run, and never accepts or returns a secret.
Errors
| Code | Status | Meaning |
|---|---|---|
provider_key_not_found | 404 | The id matches no key in the organization. |
field_read_only | 400 | A PATCH sends etag, custom, or bedrock.access_key_id, auth_mode or session_token. Rotate or add a key to change credentials. |
default_change_required | 400 | is_default false on the current default. Make another key default first. |
dry_run_unsupported | 400 | A rotate or transfer sent dry_run. |
missing_idempotency_key | 400 | A transfer has no Idempotency-Key. |
invalid_organization_id | 400 | The transfer destination is the current organization. |
account_token_required | 403 | A transfer uses a key of a named organization. |
transfer_forbidden | 403 | The API key's creator is not an admin of both organizations, or the destination is outside the account. |
provider_key_disabled | 409 | A disabled key cannot be made default. |
provider_key_enabled | 409 | A delete names an enabled key. Disable it first. |
provider_key_in_use | 409 | Routers, model groups or a policy use the key. details lists up to 20 routers and model groups. |
transfer_conflict | 409 | The source changed, became the default, or the transfer conflicted. |
concurrent_update | 409 | The key changed at the same time. Read it again and retry. |