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`	Optional[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. Defaults to the authenticated entity’s default workspace.	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.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. Defaults to the authenticated entity’s default workspace; use the workspace_id body field to scope to a different workspace. Treat the raw key as write-only; it is never returned after creation. 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_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_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.	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. Defaults to the authenticated entity’s default workspace.	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). 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_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_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.	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