Example Usage
import { BYOKKey } from "@openrouter/sdk/models";
let value: BYOKKey = {
allowedApiKeyHashes: null,
allowedModels: null,
allowedUserIds: null,
createdAt: "2025-08-24T10:30:00Z",
declaredRegion: null,
declaredZdr: null,
disabled: false,
id: "11111111-2222-3333-4444-555555555555",
isByokOnly: false,
isFallback: false,
isRequired: false,
label: "sk-...AbCd",
provider: "openai",
sortOrder: 0,
workspaceId: "550e8400-e29b-41d4-a716-446655440000",
};
Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
allowedApiKeyHashes | string[] | :heavy_check_mark: | Optional allowlist of OpenRouter API key hashes (api_keys.hash) that may use this credential. null means no restriction. | [ “f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943” ] |
allowedModels | string[] | :heavy_check_mark: | Optional allowlist of model slugs this credential may be used for. null means no restriction. | null |
allowedUserIds | string[] | :heavy_check_mark: | Optional allowlist of user IDs that may use this credential. null means no restriction. | null |
createdAt | string | :heavy_check_mark: | ISO timestamp of when the credential was created. | 2025-08-24T10:30:00Z |
declaredRegion | models.BYOKKeyDeclaredRegion | :heavy_check_mark: | 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. | null |
declaredZdr | boolean | :heavy_check_mark: | 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. | null |
disabled | boolean | :heavy_check_mark: | Whether this credential is currently disabled. | false |
id | string | :heavy_check_mark: | Stable public identifier for this BYOK credential. | 11111111-2222-3333-4444-555555555555 |
isByokOnly | boolean | :heavy_check_mark: | 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. | false |
isFallback | boolean | :heavy_check_mark: | 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. | false |
isRequired | boolean | :heavy_check_mark: | 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. | false |
label | string | :heavy_check_mark: | Short masked snippet of the key (e.g. the first/last few characters) used to identify it in the UI. | sk-…AbCd |
name | string | :heavy_minus_sign: | Optional human-readable name for the credential. | Production OpenAI Key |
provider | models.BYOKProviderSlug | :heavy_check_mark: | The upstream provider this credential authenticates against, as a lowercase slug (e.g. openai, anthropic, amazon-bedrock). | openai |
sortOrder | number | :heavy_check_mark: | Position within the provider — credentials are tried in ascending sort order. | 0 |
workspaceId | string | :heavy_check_mark: | 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. | 550e8400-e29b-41d4-a716-446655440000 |