mirror of
https://github.com/wassname/openrouter-python-sdk-retry-errors.git
synced 2026-07-29 11:23:49 +08:00
---
title: "APIKeys"
description: "API key management endpoints"
---
## Overview
API key management endpoints
### Available Operations
* [get_current_key_metadata](#get_current_key_metadata) - Get current API key
* [list](#list) - List API keys
* [create](#create) - Create a new API key
* [delete](#delete) - Delete an API key
* [get](#get) - Get a single API key
* [update](#update) - Update an API key
## get_current_key_metadata
Get information on the API key associated with the current authentication session
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> |
| `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.<br/> |
| `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.<br/> |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
### Response
**[operations.GetCurrentKeyResponse](../../operations/getcurrentkeyresponse.mdx)**
### 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](/docs/guides/overview/auth/management-api-keys) required.
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> | |
| `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.<br/> | |
| `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.<br/> | |
| `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]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.ListResponse](../../operations/listresponse.mdx)**
### Errors
| 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 plaintext `key` is returned only in this response. Treat it as a write-only, sensitive value; it cannot be retrieved later. [Management key](/docs/guides/overview/auth/management-api-keys) required.
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> | |
| `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.<br/> | |
| `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.<br/> | |
| `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](https://docs.python.org/3/library/datetime.html#date-objects) | :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]](../../operations/createkeyslimitreset.mdx) | :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]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.CreateKeysResponse](../../operations/createkeysresponse.mdx)**
### 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. [Management key](/docs/guides/overview/auth/management-api-keys) required.
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> | |
| `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.<br/> | |
| `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.<br/> | |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.DeleteKeysResponse](../../operations/deletekeysresponse.mdx)**
### 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](/docs/guides/overview/auth/management-api-keys) required.
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> | |
| `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.<br/> | |
| `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.<br/> | |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.GetKeyResponse](../../operations/getkeyresponse.mdx)**
### 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. [Management key](/docs/guides/overview/auth/management-api-keys) required.
### Example Usage
```python
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.<br/>This is used to track API usage per application.<br/> | |
| `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.<br/> | |
| `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.<br/> | |
| `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]](../../operations/updatekeyslimitreset.mdx) | :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]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.UpdateKeysResponse](../../operations/updatekeysresponse.mdx)**
### 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 | \*/\* |