APIKeys - Python SDK

APIKeys method reference

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

API key management endpoints

Available Operations

get_current_key_metadata

Get information on the API key associated with the current authentication session

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.api_keys.get_current_key_metadata()
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescription
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.GetCurrentKeyResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

list

List all API keys for the authenticated user. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.api_keys.list()
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
include_disabledOptional[bool]Whether to include disabled API keys in the responsefalse
offsetOptional[int]Number of API keys to skip for pagination0
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

create

Create a new API key for the authenticated user. Management key required.

Example Usage

1from openrouter import OpenRouter
2from openrouter.utils import parse_datetime
3import os
4
5with OpenRouter(
6 http_referer="<value>",
7 x_open_router_title="<value>",
8 x_open_router_categories="<value>",
9 api_key=os.getenv("OPENROUTER_API_KEY", ""),
10) as open_router:
11
12 res = open_router.api_keys.create(name="My New API Key", expires_at=parse_datetime("2027-12-31T23:59:59Z"), include_byok_in_limit=True, limit=50, limit_reset="monthly")
13
14 # Handle response
15 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
namestr✔️Name for the new API keyMy New API Key
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
creator_user_idOptionalNullable[str]Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key.user_2dHFtVWx2n56w6HkM0000000000
expires_atdateOptional ISO 8601 UTC timestamp when the API key should expire. Must be UTC, other timezones will be rejected2027-12-31T23:59:59Z
include_byok_in_limitOptional[bool]Whether to include BYOK usage in the limittrue
limitOptional[float]Optional spending limit for the API key in USD50
limit_resetOptionalNullable[operations.CreateKeysLimitReset]Type of limit reset for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday.monthly
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.CreateKeysResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

delete

Delete an existing API key. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.api_keys.delete(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
hashstr✔️The hash identifier of the API key to deletef01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.DeleteKeysResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

get

Get a single API key by hash. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.api_keys.get(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
hashstr✔️The hash identifier of the API key to retrievef01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.GetKeyResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

update

Update an existing API key. Management key required.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.api_keys.update(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943", disabled=False, include_byok_in_limit=True, limit=75, limit_reset="daily", name="Updated API Key Name")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
hashstr✔️The hash identifier of the API key to updatef01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
disabledOptional[bool]Whether to disable the API keyfalse
include_byok_in_limitOptional[bool]Whether to include BYOK usage in the limittrue
limitOptional[float]New spending limit for the API key in USD75
limit_resetOptionalNullable[operations.UpdateKeysLimitReset]New limit reset type for the API key (daily, weekly, monthly, or null for no reset). Resets happen automatically at midnight UTC, and weeks are Monday through Sunday.daily
nameOptional[str]New name for the API keyUpdated API Key Name
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.UpdateKeysResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*