Overview
BYOK endpointsAvailable Operations
- list - List BYOK provider credentials
- create - Create a BYOK provider credential
- delete - Delete a BYOK provider credential
- get - Get a BYOK provider credential
- update - Update a BYOK provider credential
list
List the bring-your-own-key (BYOK) provider credentials for the authenticated entity’s default workspace. Use theworkspace_id query parameter to scope the result to a different workspace, or the provider query parameter to filter by upstream provider. Management key required.
Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.byok.list(offset=0, limit=50)
while res is not None:
# Handle items
res = res.next()
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
offset | OptionalNullable[int] | :heavy_minus_sign: | Number of records to skip for pagination | 0 |
limit | Optional[int] | :heavy_minus_sign: | Maximum number of records to return (max 100) | 50 |
workspace_id | Optional[str] | :heavy_minus_sign: | Optional workspace ID to filter by. When omitted, resolves to the account’s default workspace; if that default has been deleted, the request returns a 400 and you must pass workspace_id explicitly. | 550e8400-e29b-41d4-a716-446655440000 |
provider | Optional[operations.Provider] | :heavy_minus_sign: | Optional provider slug to filter by (e.g. openai, anthropic, amazon-bedrock). | openai |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
operations.ListBYOKKeysResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
create
Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. Whenworkspace_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.
Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.byok.create(key="sk-proj-abc123...", provider="openai", name="Production OpenAI Key")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
key | str | :heavy_check_mark: | The raw provider API key or credential. This value is encrypted at rest and never returned in API responses. | sk-proj-abc123… |
provider | components.BYOKProviderSlug | :heavy_check_mark: | The upstream provider this credential authenticates against, as a lowercase slug (e.g. openai, anthropic, amazon-bedrock). | openai |
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
allowed_api_key_hashes | List[str] | :heavy_minus_sign: | 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. | [ “f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943” ] |
allowed_models | List[str] | :heavy_minus_sign: | Optional allowlist of model slugs this credential may be used for. null means no restriction. | null |
allowed_user_ids | List[str] | :heavy_minus_sign: | Optional allowlist of user IDs that may use this credential. null means no restriction. | null |
declared_zdr | OptionalNullable[bool] | :heavy_minus_sign: | 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. | null |
disabled | Optional[bool] | :heavy_minus_sign: | Whether this credential should be created in a disabled state. | false |
is_byok_only | Optional[bool] | :heavy_minus_sign: | 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. | false |
is_fallback | Optional[bool] | :heavy_minus_sign: | 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 |
is_required | Optional[bool] | :heavy_minus_sign: | 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. | false |
name | OptionalNullable[str] | :heavy_minus_sign: | Optional human-readable name for the credential. | Production OpenAI Key |
workspace_id | Optional[str] | :heavy_minus_sign: | 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. | 550e8400-e29b-41d4-a716-446655440000 |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.CreateBYOKKeyResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
delete
Delete (soft-delete) a bring-your-own-key (BYOK) provider credential by itsid. The encrypted key material is wiped and the record is marked as deleted. Management key required.
Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.byok.delete(id="11111111-2222-3333-4444-555555555555")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.DeleteBYOKKeyResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
get
Get a single bring-your-own-key (BYOK) provider credential by itsid. Management key required.
Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.byok.get(id="11111111-2222-3333-4444-555555555555")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.GetBYOKKeyResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
update
Update an existing bring-your-own-key (BYOK) provider credential by itsid. 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.
Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.byok.update(id="11111111-2222-3333-4444-555555555555", disabled=False, name="Updated OpenAI Key")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | str | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
http_referer | Optional[str] | :heavy_minus_sign: | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
allowed_api_key_hashes | List[str] | :heavy_minus_sign: | 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. | [ “f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943” ] |
allowed_models | List[str] | :heavy_minus_sign: | Optional allowlist of model slugs this credential may be used for. null means no restriction. | null |
allowed_user_ids | List[str] | :heavy_minus_sign: | Optional allowlist of user IDs that may use this credential. null means no restriction. | null |
declared_zdr | OptionalNullable[bool] | :heavy_minus_sign: | 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. | null |
disabled | Optional[bool] | :heavy_minus_sign: | Whether this credential is disabled. | false |
is_byok_only | Optional[bool] | :heavy_minus_sign: | 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. | false |
is_fallback | Optional[bool] | :heavy_minus_sign: | 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. | false |
is_required | Optional[bool] | :heavy_minus_sign: | 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. | false |
key | Optional[str] | :heavy_minus_sign: | 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. | sk-proj-newkey456… |
name | OptionalNullable[str] | :heavy_minus_sign: | Optional human-readable name for the credential. | Updated OpenAI Key |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.UpdateBYOKKeyResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |