APIKeys - OpenRouter | Documentation

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

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.api_keys.get_current_key_metadata()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`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

operations.GetCurrentKeyResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

list

List all API keys for the authenticated user. 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.api_keys.list()

    # Handle response
    print(res)

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.
`include_disabled`	Optional[bool]	:heavy_minus_sign:	Whether to include disabled API keys in the response	false
`offset`	OptionalNullable[int]	:heavy_minus_sign:	Number of API keys to skip for pagination	0
`workspace_id`	Optional[str]	:heavy_minus_sign:	Filter API keys by workspace ID. By default, keys in the default workspace are returned.	0df9e665-d932-5740-b2c7-b52af166bc11
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.ListResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

create

Create a new API key for the authenticated user. The plaintext key is returned only in this response. Treat it as a write-only, sensitive value; it cannot be retrieved later. Authenticate with a management key, or with a Connect client secret. external_user and external_api_key are accepted only with a client secret, and external_user is required there; supplying either field with a management key is rejected with 403.

Example Usage

from openrouter import OpenRouter
from openrouter.utils import parse_datetime
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.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")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`name`	str	:heavy_check_mark:	Name for the new API key	My New API Key
`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.
`creator_user_id`	OptionalNullable[str]	:heavy_minus_sign:	Optional user ID of the key creator. Only meaningful for organization-owned keys where a specific member is creating the key.	user_2dHFtVWx2n56w6HkM0000000000
`expires_at`	date	:heavy_minus_sign:	Optional ISO 8601 UTC timestamp when the API key should expire. Must be UTC, other timezones will be rejected	2027-12-31T23:59:59Z
`external_api_key`	Optional[str]	:heavy_minus_sign:	Optional partner-supplied API key. Stored as a SHA-256 hash and never returned. Accepted only when authenticating with a Connect client secret; supplying it with a management key is rejected with 403.
`external_user`	Optional[str]	:heavy_minus_sign:	Partner’s end-user identifier for attribution, between 1 and 512 characters. Accepted only when authenticating with a Connect client secret, where it is required; supplying it with a management key is rejected with 403.
`include_byok_in_limit`	Optional[bool]	:heavy_minus_sign:	Whether to include BYOK usage in the limit	true
`limit`	OptionalNullable[float]	:heavy_minus_sign:	Optional spending limit for the API key in USD	50
`limit_reset`	OptionalNullable[operations.CreateKeysLimitReset]	:heavy_minus_sign:	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_id`	Optional[str]	:heavy_minus_sign:	The workspace to create the API key in. Defaults to the default workspace if not provided.	0df9e665-d932-5740-b2c7-b52af166bc11
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.CreateKeysResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

Delete an existing API key. Authenticate with a management key, or with a Connect client secret. A client secret reaches only the keys that same client created; any other key responds as if it does not exist.

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.api_keys.delete(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`hash`	str	:heavy_check_mark:	The hash identifier of the API key to delete	f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
`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

operations.DeleteKeysResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get

Get a single API key by hash. 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.api_keys.get(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`hash`	str	:heavy_check_mark:	The hash identifier of the API key to retrieve	f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
`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

operations.GetKeyResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

update

Update an existing API key. Authenticate with a management key, or with a Connect client secret. A client secret reaches only the keys that same client created; any other key responds as if it does not exist.

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.api_keys.update(hash="f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943", disabled=False, include_byok_in_limit=True, limit=75, limit_reset="daily", name="Updated API Key Name")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`hash`	str	:heavy_check_mark:	The hash identifier of the API key to update	f01d52606dc8f0a8303a7b5cc3fa07109c2e346cec7c0a16b40de462992ce943
`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.
`disabled`	Optional[bool]	:heavy_minus_sign:	Whether to disable the API key	false
`include_byok_in_limit`	Optional[bool]	:heavy_minus_sign:	Whether to include BYOK usage in the limit	true
`limit`	OptionalNullable[float]	:heavy_minus_sign:	New spending limit for the API key in USD	75
`limit_reset`	OptionalNullable[operations.UpdateKeysLimitReset]	:heavy_minus_sign:	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
`name`	Optional[str]	:heavy_minus_sign:	New name for the API key	Updated API Key Name
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.UpdateKeysResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​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

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