multi-router.aidocs

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

MethodPathDescriptionScope
GET/v1/provider-keysList provider keys, without secrets. Paginated.provider_keys:read
POST/v1/provider-keysAdd 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}/rotateReplace the secret, keeping the key id. Returns 200 with the secret once.provider_keys:write
POST/v1/provider-keys/{id}/transferCopy 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

FieldType
idstring
The key id, prefixed llpk_, used in provider_key_id.
namestring, required on create
1 to 80 characters.
descriptionstring or null
Up to 2,000 characters.
providerstring, required on create
The provider id. Fixed.
secretstring, required on create and rotate
The credential. Never returned by reads.
enabledboolean
Defaults to true.
is_defaultboolean
Whether this is the provider's default key. Setting true moves the default from the previous key.
bedrockobject
AWS Bedrock: region, auth_mode, access_key_id, and on create session_token. PATCH changes only region.
vertexobject
Google Vertex: project_id and region.
openaiobject
OpenAI: data_residency, and on create organization. PATCH changes only data_residency.
customobject
Custom endpoints: base_url and api_format. Fixed after create.
key_prefixstring
The start of the secret, to recognize it.
etagstring
The quoted version, for If-Match.
Add a keybash
curl -X POST https://api.multi-router.ai/v1/provider-keys \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data @key-create.json
key-create.jsonjson
{ "name": "Anthropic production", "provider": "anthropic", "secret": "sk-ant-api03-…" }
Response 201json
{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": {
    "id": "llpk_4Vd8Qm2RtL",
    "object": "provider_key",
    "name": "Anthropic production",
    "description": null,
    "provider": "anthropic",
    "key_prefix": "sk-ant-api",
    "enabled": true,
    "is_default": true,
    "etag": "\"1\"",
    "created_at": "2026-10-01T17:02:11Z",
    "updated_at": "2026-10-01T17:02:11Z"
  },
  "secret": "sk-ant-api03-…"
}

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.

Copy a key to another organizationbash
curl -X POST https://api.multi-router.ai/v1/provider-keys/llpk_4Vd8Qm2RtL/transfer \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "organization_id": "org_3Hd8Kw2PqZ", "mode": "copy" }'

Errors

CodeStatusMeaning
provider_key_not_found404The id matches no key in the organization.
field_read_only400A PATCH sends etag, custom, or bedrock.access_key_id, auth_mode or session_token. Rotate or add a key to change credentials.
default_change_required400is_default false on the current default. Make another key default first.
dry_run_unsupported400A rotate or transfer sent dry_run.
missing_idempotency_key400A transfer has no Idempotency-Key.
invalid_organization_id400The transfer destination is the current organization.
account_token_required403A transfer uses a key of a named organization.
transfer_forbidden403The API key's creator is not an admin of both organizations, or the destination is outside the account.
provider_key_disabled409A disabled key cannot be made default.
provider_key_enabled409A delete names an enabled key. Disable it first.
provider_key_in_use409Routers, model groups or a policy use the key. details lists up to 20 routers and model groups.
transfer_conflict409The source changed, became the default, or the transfer conflicted.
concurrent_update409The key changed at the same time. Read it again and retry.
RoutersIntegrations
Was this helpful?