Sign in
BYOK

Create a BYOK provider credential

Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. When workspace_id is omitted, the credential is created in the default workspace; if that default has been deleted, the request returns a 400 and you must pass workspace_id explicitly. Treat the raw key as write-only; it is never returned after creation. Use allowed_api_key_hashes to restrict the credential to specific OpenRouter API keys. Management key required.

post/byok

Request body

allowed_api_key_hashesstring[] nullable

Optional allowlist of OpenRouter API key hashes (api_keys.hash) that may use this credential. null means no restriction. Must contain at least one hash if provided. Hashes that do not belong to your account return a 400.

allowed_modelsstring[] nullable

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

allowed_user_idsstring[] nullable

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

declared_zdrboolean nullable

Your declaration of whether the upstream provider account behind this credential has zero data retention (ZDR). null inherits OpenRouter's data policy for the provider's endpoint; true declares the account ZDR so requests that require ZDR may route to this credential even when the shared endpoint retains data; false declares it non-ZDR so such requests never route to it. Self-declared and not verified by OpenRouter. Defaults to null.

disabledboolean

Whether this credential should be created in a disabled state.

is_byok_onlyboolean

Whether OpenRouter's shared endpoints on this provider are removed for every model, including models outside allowed_models and after all of your keys for the provider fail. The provider is skipped instead of spending OpenRouter credits. Only valid on non-fallback credentials. Defaults to false.

is_fallbackboolean

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

is_requiredboolean

Whether OpenRouter's shared endpoints on this provider are removed for the models this credential applies to (its allowed_models, or every model when null). Requests for those models run only on your keys; models outside the allowlist may still fall back to shared capacity on this provider. Defaults to false.

keystring required

The raw provider API key or credential. This value is encrypted at rest and never returned in API responses.

namestring nullable

Optional human-readable name for the credential.

provider'ai21' | 'aion-labs' | 'akashml' | 'alibaba' | 'amazon-bedrock' | 'amazon-bedrock/claude-on-aws' | 'amazon-nova' | 'ambient' | 'anthropic' | 'anthropic/2' | 'arcee-ai' | 'assemblyai' | 'atlas-cloud' | 'avian' | 'azure' | 'baidu' | 'baseten' | 'black-forest-labs' | 'byteplus' | 'cerebras' | 'chutes' | 'cirrascale' | 'clarifai' | 'claude-on-aws' | 'cloudflare' | 'cohere' | 'coreweave' | 'cosine' | 'crusoe' | 'darkbloom' | 'databricks' | 'decart' | 'deepgram' | 'deepinfra' | 'deepseek' | 'dekallm' | 'digitalocean' | 'featherless' | 'fireworks' | 'fish-audio' | 'friendli' | 'gmicloud' | 'google-ai-studio' | 'google-vertex' | 'groq' | 'heygen' | 'inception' | 'inceptron' | 'inferact-vllm' | 'inference-net' | 'infermatic' | 'inflection' | 'io-net' | 'ionstream' | 'krea' | 'liquid' | 'makora' | 'mancer' | 'mara' | 'meta' | 'minimax' | 'mistral' | 'modal' | 'modelrun' | 'modular' | 'moonshotai' | 'morph' | 'near-ai' | 'nebius' | 'nex-agi' | 'nextbit' | 'novita' | 'nvidia' | 'ollama' | 'open-inference' | 'openai' | 'parasail' | 'perceptron' | 'perplexity' | 'phala' | 'poolside' | 'primeintellect' | 'quiver' | 'recraft' | 'reka' | 'relace' | 'respan' | 'runway' | 'sail-research' | 'sakana' | 'sakana-ai' | 'sambanova' | 'scaledown' | 'seed' | 'siliconflow' | 'sourceful' | 'stepfun' | 'streamlake' | 'switchpoint' | 'tencent' | 'tenstorrent' | 'thinkingmachines' | 'together' | 'typesafe' | 'unbiased' | 'upstage' | 'venice' | 'voyageai' | 'wafer' | 'wandb' | 'wandb-legacy' | 'xai' | 'xiaomi' | 'z-ai' required

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

workspace_idstring uuid

Optional workspace ID to scope the credential to. When omitted, the credential is created in the account's default workspace; if that default has been deleted, the request returns a 400 and you must pass workspace_id explicitly.

Example request

{
  "key": "sk-proj-abc123...",
  "name": "Production OpenAI Key",
  "provider": "openai"
}

Response

BYOK credential created successfully

Example response

{
  "data": {
    "allowed_api_key_hashes": null,
    "allowed_models": null,
    "allowed_user_ids": null,
    "created_at": "2025-08-24T10:30:00Z",
    "declared_zdr": null,
    "disabled": false,
    "id": "11111111-2222-3333-4444-555555555555",
    "is_byok_only": false,
    "is_fallback": false,
    "is_required": false,
    "label": "sk-...AbCd",
    "name": "Production OpenAI Key",
    "provider": "openai",
    "sort_order": 0,
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Changes

Changed in 36 of the 303 revisions of this API.73444

  • 31b1cd25caca11See the full diff
    • ●

      added the new respan enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new respan enum value to the request property

      request-property-enum-value-added

  • 4c8b9dc76c4511See the full diff
    • ●

      added the new scaledown enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new scaledown enum value to the request property

      request-property-enum-value-added

  • 91342dd3fd0f2See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the required property ///// to the response with the status

      response-required-property-added

  • 3066544509b511See the full diff
    • ●

      added the new unbiased enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new unbiased enum value to the request property

      request-property-enum-value-added

  • 2de027b6dfcd11See the full diff
    • ●

      added the new typesafe enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new typesafe enum value to the request property

      request-property-enum-value-added

  • 54ab2e9ba85711See the full diff
    • ●

      added the new assemblyai enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new assemblyai enum value to the request property

      request-property-enum-value-added

  • 34a00258bec933See the full diff
    • ●

      added the new amazon-bedrock/claude-on-aws enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new anthropic/2 enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new claude-on-aws enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new amazon-bedrock/claude-on-aws enum value to the request property

      request-property-enum-value-added

    • ○

      added the new anthropic/2 enum value to the request property

      request-property-enum-value-added

    • ○

      added the new claude-on-aws enum value to the request property

      request-property-enum-value-added

  • 5d13b1d2e3ac11See the full diff
    • ●

      added the new near-ai enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new near-ai enum value to the request property

      request-property-enum-value-added

  • 029d7d64cf914See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the required property ///// to the response with the status

      response-required-property-added

    • ○

      added the required property ///// to the response with the status

      response-required-property-added

  • 933a13bf45f0112See the full diff
    • ▲

      removed the enum value prime-intellect of the request property

      request-property-enum-value-removed

    • ●

      added the new primeintellect enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ○

      added the new primeintellect enum value to the request property

      request-property-enum-value-added

    • ○

      removed the prime-intellect enum value from the ///// response property for the response status

      response-property-enum-value-removed