> ## Documentation Index > Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # BYOK > BYOK endpoints ## Overview BYOK endpoints ### Available Operations * [list](#list) - List BYOK provider credentials * [create](#create) - Create a BYOK provider credential * [delete](#delete) - Delete a BYOK provider credential * [get](#get) - Get a BYOK provider credential * [update](#update) - Update a BYOK provider credential ## list List the bring-your-own-key (BYOK) provider credentials for the authenticated entity's default workspace. Use the `workspace_id` query parameter to scope the result to a different workspace, or the `provider` query parameter to filter by upstream provider. [Management key](/docs/client-sdks/python/docs/guides/overview/auth/management-api-keys) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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\]](../../operations/provider.mdx) | :heavy\_minus\_sign: | Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`). | openai | | `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[operations.ListBYOKKeysResponse](../../operations/listbyokkeysresponse.mdx)** ### Errors | 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. When `workspace_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](/docs/client-sdks/python/docs/guides/overview/auth/management-api-keys) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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](../../components/byokproviderslug.mdx) | :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 | | `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\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.CreateBYOKKeyResponse](../../components/createbyokkeyresponse.mdx)** ### Errors | 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 its `id`. The encrypted key material is wiped and the record is marked as deleted. [Management key](/docs/client-sdks/python/docs/guides/overview/auth/management-api-keys) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.DeleteBYOKKeyResponse](../../components/deletebyokkeyresponse.mdx)** ### Errors | 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 its `id`. [Management key](/docs/client-sdks/python/docs/guides/overview/auth/management-api-keys) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.GetBYOKKeyResponse](../../components/getbyokkeyresponse.mdx)** ### Errors | 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 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/client-sdks/python/docs/guides/overview/auth/management-api-keys) required. ### Example Usage ```python theme={null} from openrouter import OpenRouter import os with OpenRouter( http_referer="", x_open_router_title="", x_open_router_categories="", 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 | | `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\]](../../models/utils/retryconfig.mdx) | :heavy\_minus\_sign: | Configuration to override the default retry behavior of the client. | | ### Response **[components.UpdateBYOKKeyResponse](../../components/updatebyokkeyresponse.mdx)** ### Errors | Error Type | Status Code | Content Type | | ---------------------------------- | ----------- | ---------------- | | errors.BadRequestResponseError | 400 | application/json | | errors.UnauthorizedResponseError | 401 | application/json | | errors.NotFoundResponseError | 404 | application/json | | errors.InternalServerResponseError | 500 | application/json | | errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |