Bring Your Own Key (BYOK)

BYOK lets an organization admin save provider credentials compatible with the Vercel AI Gateway and bind one saved key to an agent. When the agent runs a chat with a BYOK binding, the request authenticates with the organization's own credentials instead of the platform's system key.

Usage from BYOK-bound agents does not count against the organization's plan token limits. It is still logged and aggregated so the org has full visibility into both platform and BYOK spend side by side.

Who Can Use It

BYOK management is an admin-only capability. It requires the new ai.api-key claim family:

• ai.api-key.create
• ai.api-key.read
• ai.api-key.update
• ai.api-key.delete
• ai.api-key.bind
• ai.api-key.unbind

These claims are assigned to Organization Owner and Admin roles by default. Platform-level usage (cross-org) is covered by the existing platform.manage_all policy and does not need BYOK-specific claims.

See RBAC and Custom Roles for the full claim matrix.

Supported Providers (v1)

Provider slug	Credential fields	Notes
anthropic	apiKey	Claude model family
openai	apiKey	GPT model family
azure	apiKey, resourceName	Azure OpenAI deployment
vertex	project, location, googleCredentials.privateKey, googleCredentials.clientEmail	Service-account JSON fields
bedrock	accessKeyId, secretAccessKey, region?	AWS IAM credentials
vercel-ai-gateway	apiKey	Your team's OWN Vercel AI Gateway key; routes through your gateway instead of ours

Credentials are encrypted at rest with AES-256-GCM. Only the last four characters (lastFour) are retained in plaintext for display purposes. The full credential is never returned by the API after save.

Save a Key

From the panel BYOK tab:

1. Open the org BYOK settings tab.
2. Click Add key.
3. Pick a provider from the supported list.
4. Fill in the credential fields.
5. Click Save.

The API route is POST /ai/api-keys (payload shape defined in packages/schemas/src/ai/api-keys/create-api-key.schema.ts).

Credentials are write-once

After save, the plaintext credential is never shown again. Only lastFour and a human-readable name are visible. To rotate, delete the key and create a new one.

Bind a Key to an Agent

From the agent edit dialog:

1. Open the agent.
2. Go to the Brain step.
3. In the model selector, open the API Key dropdown.
4. Select a compatible saved key, or click + Save new key to create one inline without leaving the agent edit flow.
5. Click Save agent.

The API route is PUT /ai/agents/:agentId/api-key with body { "apiKeyId": "<uuid>" }. Use the same endpoint with { "apiKeyId": null } to unbind.

Compatibility Rules

The key's provider must be one of the model's compatible providers, as reported by the Vercel AI Gateway model registry.

Exception: vercel-ai-gateway keys are compatible with any model. The gateway routes internally using the customer's team credentials, so the platform does not need to match the provider to the model.

If an incompatible pair is selected, PUT /ai/agents/:agentId/api-key returns HTTP 400 with code AI.API_KEY_PROVIDER_INCOMPATIBLE_WITH_MODEL.

Fail-Hard Behavior

Fail-hard is intentional. No fallback to system key.

When a BYOK-bound agent runs a chat and the organization's credentials are invalid, expired, or hit a provider rate limit, the chat request fails. The system does not silently fall back to the platform's system key.

This is deliberate:

• Orgs can be confident their own credentials are being used.
• Platform credits cannot be accidentally charged for BYOK traffic.
• Credential issues surface immediately instead of being masked.

The gateway request is constructed with gateway.only set to the BYOK credential so the AI SDK cannot fall back to any other authentication source.

Usage Reporting

Every chat request records a TokenUsageLog:

• BYOK chats use source='byok' and include the apiKeyId that authorized the request.
• System-key chats use source='system'.

The org_token_usage_summary aggregate rolls up per (orgId, month, source) so dashboards can show BYOK and system usage as separate breakdowns.

Plan-limit enforcement filters on source='system' only. BYOK usage is always allowed, regardless of plan caps, but remains fully visible to admins under the BYOK breakdown in usage dashboards.

Deleting a Key

A key cannot be deleted while it is bound to any agent. The API returns HTTP 409 with code AI.API_KEY_IN_USE and includes the blocking agent IDs in the response body:

{
  "code": "AI.API_KEY_IN_USE",
  "message": "This API key is bound to one or more agents and cannot be deleted.",
  "agentIds": ["019e0a1f-...", "019e0a20-..."]
}

To delete, first unbind the key from each listed agent, then call DELETE /ai/api-keys/:id again.

Rotation (v1 Limitation)

In v1, in-place credential rotation is not supported. To rotate:

1. Create a new key with the new credential.
2. Bind each affected agent to the new key.
3. Delete the old key.

Only the key name can be updated in place via PATCH /ai/api-keys/:id.

Not in v1

• Connection-test button that pings the provider before save
• BYOK for embedding models (embeddings still use the system key)
• Cross-org key sharing
• BYOK-specific billing reports
• Master-key rotation tooling for the AES-256-GCM wrapping key

Troubleshooting

Symptom	Likely cause	Fix
400 AI.API_KEY_PROVIDER_INCOMPATIBLE_WITH_MODEL	Selected key's provider is not in the model's compatible list	Pick a different key or change the agent's model
409 AI.API_KEY_IN_USE on DELETE /ai/api-keys/:id	Key is still bound to one or more agents	Unbind from the agentIds in the response, then retry
5xx on chat with BYOK-bound agent	Provider credential is invalid, expired, or rate-limited	Verify the credential in the provider console; rotate if needed
404 AI.API_KEY_NOT_FOUND on bind	Key was deleted or belongs to a different org	Reload the BYOK list; re-save the key if needed

Gateway error codes surfaced in the chat stream include the provider name in the message (for example anthropic.authentication_error), which makes it easier to tell which credential failed when an org has multiple BYOK keys.

See Also

• RBAC and Custom Roles — AI API Keys (BYOK)
• Agent Management
• Chat and Message Streaming
• ADR 009 — BYOK via Vercel AI Gateway
• Vercel AI Gateway — Authentication and BYOK (external)