For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
ModelsChatRankingsDocs
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
    • Overview
    • Usage for Agents
  • TypeScript SDK
    • Overview
  • Python SDK
    • Overview
      • Analytics
      • APIKeys
      • Byok
      • Chat
      • Credits
      • Embeddings
      • Endpoints
      • Generations
      • Guardrails
      • OAuth
      • Observability
      • Organization
      • Presets
      • Providers
      • Rerank
      • Beta.Responses
      • Transcriptions
      • Speech
      • VideoGeneration
      • Workspaces
  • Go SDK
  • DevTools
    • Overview
    • Migrating to @openrouter/agent
LogoLogo
ModelsChatRankingsDocs
On this page
  • Overview
  • Available Operations
  • get_current_key_metadata
  • Example Usage
  • Parameters
  • Response
  • Errors
  • 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
Python SDKAPI Reference

APIKeys - Python SDK

APIKeys method reference
Was this page helpful?
Previous

Byok - Python SDK

Byok method reference
Next
Built with

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 current API key
  • list - List API keys
  • create - Create a new API key
  • delete - Delete an API key
  • get - Get a single API key
  • update - Update an API key

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
workspace_idOptional[str]➖Filter API keys by workspace ID. By default, keys in the default workspace are returned.0df9e665-d932-5740-b2c7-b52af166bc11
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_atdate➖Optional 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
limitOptionalNullable[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
workspace_idOptional[str]➖The workspace to create the API key in. Defaults to the default workspace if not provided.0df9e665-d932-5740-b2c7-b52af166bc11
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.ForbiddenResponseError403application/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
limitOptionalNullable[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*/*