Overview
API key management endpointsAvailable 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 sessionExample 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.GetCurrentKeyResponseErrors
| 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 | Optional[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.ListResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| 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 plaintextkey is returned only in this response. Treat it as a write-only, sensitive value; it cannot be retrieved later. Management key required.
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 |
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.CreateKeysResponseErrors
| 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. 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.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.DeleteKeysResponseErrors
| 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.GetKeyResponseErrors
| 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. 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.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.UpdateKeysResponseErrors
| 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 | */* |