For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
ModelsChatRankingsDocs
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
  • API Guides
    • Overview
    • Streaming
    • Embeddings
    • Limits
    • Authentication
    • Parameters
    • Errors and Debugging
  • API Reference
      • GETList BYOK provider credentials
      • POSTCreate a BYOK provider credential
      • GETGet a BYOK provider credential
      • DELDelete a BYOK provider credential
      • PATCHUpdate a BYOK provider credential
LogoLogo
ModelsChatRankingsDocs
API ReferenceByok

Create a BYOK provider credential

POST
https://openrouter.ai/api/v1/byok
POST
/api/v1/byok
$curl -X POST https://openrouter.ai/api/v1/byok \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "key": "sk-proj-abc123...",
>  "provider": "openai",
>  "name": "Production OpenAI Key"
>}'
1{
2  "data": {
3    "allowed_api_key_hashes": null,
4    "allowed_models": null,
5    "allowed_user_ids": null,
6    "created_at": "2025-08-24T10:30:00Z",
7    "disabled": false,
8    "id": "11111111-2222-3333-4444-555555555555",
9    "is_fallback": false,
10    "label": "sk-...AbCd",
11    "provider": "openai",
12    "sort_order": 0,
13    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
14    "name": "Production OpenAI Key"
15  }
16}

Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. Defaults to the authenticated entity’s default workspace; use the workspace_id body field to scope to a different workspace. Management key required.

Was this page helpful?
Previous

Get a BYOK provider credential

Next
Built with

Authentication

AuthorizationBearer
API key as bearer token in Authorization header

Request

This endpoint expects an object.
keystringRequired>=1 character
The raw provider API key or credential. This value is encrypted at rest and never returned in API responses.
providerenumRequired

The upstream provider this credential authenticates against, as a lowercase slug (e.g. openai, anthropic, amazon-bedrock).

allowed_modelslist of strings or nullOptional

Optional allowlist of model slugs this credential may be used for. null means no restriction.

allowed_user_idslist of strings or nullOptional

Optional allowlist of user IDs that may use this credential. null means no restriction.

disabledbooleanOptional
Whether this credential should be created in a disabled state.
is_fallbackbooleanOptional

Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried.

namestring or nullOptional<=255 characters

Optional human-readable name for the credential.

workspace_idstringOptionalformat: "uuid"
Optional workspace ID. Defaults to the authenticated entity's default workspace.

Response

BYOK credential created successfully
dataobject
The created BYOK credential.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error