---
title: "Update a BYOK provider credential"
method: PATCH
path: "/byok/{id}"
tags: ["BYOK"]
---

# Update a BYOK provider credential

`PATCH /byok/{id}`

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](/docs/guides/overview/auth/management-api-keys) required.

## Path parameters

- `id` string, uuid, required — The BYOK credential ID (UUID).

## Request body

- UpdateBYOKKeyRequest
  - `allowed_api_key_hashes` string[], 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_models` string[], nullable — Optional allowlist of model slugs this credential may be used for. `null` means no restriction.
  - `allowed_user_ids` string[], nullable — Optional allowlist of user IDs that may use this credential. `null` means no restriction.
  - `declared_zdr` boolean, 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.
  - `disabled` boolean — Whether this credential is disabled.
  - `is_byok_only` boolean — 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_fallback` boolean — 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_required` boolean — 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.
  - `key` string — 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.
  - `name` string, nullable — Optional human-readable name for the credential.

## Response `200`

BYOK credential updated successfully

- UpdateBYOKKeyResponse
  - `data` object, required — The updated BYOK credential.
    - `allowed_api_key_hashes` string[], nullable, required — Optional allowlist of OpenRouter API key hashes (`api_keys.hash`) that may use this credential. `null` means no restriction.
    - `allowed_models` string[], nullable, required — Optional allowlist of model slugs this credential may be used for. `null` means no restriction.
    - `allowed_user_ids` string[], nullable, required — Optional allowlist of user IDs that may use this credential. `null` means no restriction.
    - `created_at` string, required — ISO timestamp of when the credential was created.
    - `declared_zdr` boolean, nullable, required — 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.
    - `disabled` boolean, required — Whether this credential is currently disabled.
    - `id` string, uuid, required — Stable public identifier for this BYOK credential.
    - `is_byok_only` boolean, required — 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.
    - `is_fallback` boolean, required — 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_required` boolean, required — 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.
    - `label` string, required — Short masked snippet of the key (e.g. the first/last few characters) used to identify it in the UI.
    - `name` string, 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' | 'runway' | 'sail-research' | 'sakana' | 'sakana-ai' | 'sambanova' | '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`).
    - `sort_order` integer, required — Position within the provider — credentials are tried in ascending sort order.
    - `workspace_id` string, uuid, nullable, required — The workspace this credential is scoped to, or `null` when it is global — usable across every workspace in the account. A `null` value does not mean the default workspace.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Authentication successful but insufficient permissions
- `404` — Not Found - Resource does not exist
- `500` — Internal Server Error - Unexpected server error

## Changes

- **2026-09-21** `91342dd3fd0f` — 2 info
  - added the new optional request property `declared_zdr`
  - added the required property `data/allOf[#/components/schemas/BYOKKey]/declared_zdr` to the response with the `200` status
- **2026-09-19** `b94291e182cc` — 1 info
  - added the non-success response with the status `403`
- **2026-09-17** `3066544509b5` — 1 warning
  - added the new `unbiased` enum value to the `data/allOf[#/components/schemas/BYOKKey]/provider` response property for the response status `200`
- **2026-09-17** `2de027b6dfcd` — 1 warning
  - added the new `typesafe` enum value to the `data/allOf[#/components/schemas/BYOKKey]/provider` response property for the response status `200`
- **2026-09-14** `54ab2e9ba857` — 1 warning
  - added the new `assemblyai` enum value to the `data/allOf[#/components/schemas/BYOKKey]/provider` response property for the response status `200`

[Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/byok/:id/patch.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/0ca3cbfb629d?raw)