Sign in
BYOK

Update a BYOK provider credential

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}

Path parameters

idstring uuid required

The BYOK credential ID (UUID).

Example:11111111-2222-3333-4444-555555555555

The BYOK credential ID (UUID).

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_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_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

Changed in 37 of the 303 revisions of this API.43411

  • 31b1cd25caca1See the full diff
    • ●

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

      response-property-enum-value-added

  • 4c8b9dc76c451See the full diff
    • ●

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

      response-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

  • b94291e182cc1See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • 3066544509b51See the full diff
    • ●

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

      response-property-enum-value-added

  • 2de027b6dfcd1See the full diff
    • ●

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

      response-property-enum-value-added

  • 54ab2e9ba8571See the full diff
    • ●

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

      response-property-enum-value-added

  • 34a00258bec93See 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

  • 5d13b1d2e3ac1See the full diff
    • ●

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

      response-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