BYOK

Update a BYOK provider credential

Changed on

Update an existing bring-your-own-key (BYOK) provider credential by its id. Include the key field to rotate the raw provider API key in-place (the previous key material is overwritten). Use allowed_api_key_hashes to restrict the credential to specific OpenRouter API keys (null clears the restriction). Management key required.

patch/byok/{id}

Request

  • Base URL: https://openrouter.ai/api/v1
  • URL: https://openrouter.ai/api/v1/byok/{id}
  • Auth: HTTP bearer

Path parameters

idstring uuid required

The BYOK credential ID (UUID).

Example:11111111-2222-3333-4444-555555555555

Request body

allowed_api_key_hashesstring[] nullable

Optional allowlist of OpenRouter API key hashes (api_keys.hash) that may use this credential. null clears the 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_region'global' | 'europe' | 'us' | 'null' nullable

Your declaration of the data region in which the upstream provider account behind this credential processes requests, used for routing eligibility on OpenRouter's regional hosts. null means undeclared and global is behaviorally identical: the credential follows the region OpenRouter records for the endpoint. europe or us lets requests to eu.openrouter.ai or us.openrouter.ai use this credential for that provider (private endpoints, endpoints pinned to another cloud region, cross-region inference profiles and video models are excluded). Self-declared and not verified by OpenRouter. For OpenAI and Fireworks the region comes from the key material (a {"api_key": ..., "region": ...} key), so the value must match the key's region. Among other providers, only Azure accepts europe or us. Omit to leave the stored value unchanged (rotating an OpenAI or Fireworks key re-derives it from the new key); null clears the declaration.

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. Omit to leave the stored value unchanged; null clears the declaration.

disabledboolean

Whether this credential is disabled.

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. Omit to leave the stored value unchanged.

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. Omit to leave the stored value unchanged.

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. Omit to leave the stored value unchanged.

keystring

A new raw provider API key to rotate the credential in-place. The previous key material is overwritten and the masked label is regenerated. Encrypted at rest and never returned in API responses.

namestring nullable

Optional human-readable name for the credential.

Example request

{
  "disabled": false,
  "name": "Updated OpenAI Key"
}

Response

BYOK credential updated successfully

Example response

{
  "data": {
    "allowed_api_key_hashes": null,
    "allowed_models": null,
    "allowed_user_ids": null,
    "created_at": "2025-08-24T10:30:00Z",
    "declared_region": null,
    "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": "Updated OpenAI Key",
    "provider": "openai",
    "sort_order": 0,
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Changes

  • e25de0f50842Revision changes
    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

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

  • 68a12e66c7faRevision changes
    • warning

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