BYOK - OpenRouter | Documentation

Overview

BYOK endpoints

Available 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 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 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.ListBYOKKeysResponse

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 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
`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.CreateBYOKKeyResponse

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 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.DeleteBYOKKeyResponse

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 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.GetBYOKKeyResponse

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 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
`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.UpdateBYOKKeyResponse

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	/

​Overview

​Available Operations

​list

​Example Usage

​Parameters

​Response

​Errors

​create

​Example Usage

​Parameters

​Response

​Errors

​delete

​Example Usage

​Parameters

​Response

​Errors

​get

​Example Usage

​Parameters

​Response

​Errors

​update

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

get

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors