wassname/openrouter-python-sdk-retry-errors
1
0
Fork 0
mirror of https://github.com/wassname/openrouter-python-sdk-retry-errors.git synced 2026-07-29 11:23:49 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d62640c385d9cb681b58f75edcd888568707f7b1
openrouter-python-sdk-retry…/docs/sdks/byok/README.mdx
T

275 lines
48 KiB
Plaintext
Raw Blame History

---
title: "Byok"
description: "BYOK endpoints"
---
## Overview
BYOK endpoints
### Available Operations
* [list](#list) - List BYOK provider credentials
* [create](#create) - Create a BYOK provider credential
* [delete](#delete) - Delete a BYOK provider credential
* [get](#get) - Get a BYOK provider credential
* [update](#update) - Update a BYOK provider credential
## list
List the bring-your-own-key (BYOK) provider credentials for the authenticated entity's default workspace. Use the `workspace_id` query parameter to scope the result to a different workspace, or the `provider` query parameter to filter by upstream provider. [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.byok.list()
while res is not None:
# Handle items
res = res.next()
```
### 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/> | |
| `offset` | *Optional[int]* | :heavy_minus_sign: | Number of records to skip for pagination | 0 |
| `limit` | *Optional[int]* | :heavy_minus_sign: | Maximum number of records to return (max 100) | 50 |
| `workspace_id` | *Optional[str]* | :heavy_minus_sign: | Optional workspace ID to filter by. Defaults to the authenticated entity's default workspace. | 550e8400-e29b-41d4-a716-446655440000 |
| `provider` | [Optional[operations.Provider]](../../operations/provider.mdx) | :heavy_minus_sign: | Optional provider slug to filter by (e.g. `openai`, `anthropic`, `amazon-bedrock`). | openai |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[operations.ListBYOKKeysResponse](../../operations/listbyokkeysresponse.mdx)**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |
## create
Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. Defaults to the authenticated entity's default workspace; use the `workspace_id` body field to scope to a different workspace. Treat the raw key as write-only; it is never returned after creation. [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.byok.create(key="sk-proj-abc123...", provider="openai", name="Production OpenAI Key")
# Handle response
print(res)
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key` | *str* | :heavy_check_mark: | The raw provider API key or credential. This value is encrypted at rest and never returned in API responses. | sk-proj-abc123... |
| `provider` | [components.BYOKProviderSlug](../../components/byokproviderslug.mdx) | :heavy_check_mark: | The upstream provider this credential authenticates against, as a lowercase slug (e.g. `openai`, `anthropic`, `amazon-bedrock`). | openai |
| `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/> | |
| `allowed_models` | List[*str*] | :heavy_minus_sign: | Optional allowlist of model slugs this credential may be used for. `null` means no restriction. | null |
| `allowed_user_ids` | List[*str*] | :heavy_minus_sign: | Optional allowlist of user IDs that may use this credential. `null` means no restriction. | null |
| `disabled` | *Optional[bool]* | :heavy_minus_sign: | Whether this credential should be created in a disabled state. | false |
| `is_fallback` | *Optional[bool]* | :heavy_minus_sign: | Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried. | false |
| `name` | *OptionalNullable[str]* | :heavy_minus_sign: | Optional human-readable name for the credential. | Production OpenAI Key |
| `workspace_id` | *Optional[str]* | :heavy_minus_sign: | Optional workspace ID. Defaults to the authenticated entity's default workspace. | 550e8400-e29b-41d4-a716-446655440000 |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[components.CreateBYOKKeyResponse](../../components/createbyokkeyresponse.mdx)**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |
## delete
Delete (soft-delete) a bring-your-own-key (BYOK) provider credential by its `id`. The encrypted key material is wiped and the record is marked as deleted. [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.byok.delete(id="11111111-2222-3333-4444-555555555555")
# Handle response
print(res)
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | *str* | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
| `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
**[components.DeleteBYOKKeyResponse](../../components/deletebyokkeyresponse.mdx)**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |
## get
Get a single bring-your-own-key (BYOK) provider credential by its `id`. [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.byok.get(id="11111111-2222-3333-4444-555555555555")
# Handle response
print(res)
```
### Parameters
| Parameter | Type | Required | Description | Example |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | *str* | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
| `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
**[components.GetBYOKKeyResponse](../../components/getbyokkeyresponse.mdx)**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |
## update
Update an existing bring-your-own-key (BYOK) provider credential by its `id`. Include the `key` field to rotate the raw provider API key in-place (the previous key material is overwritten). [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.byok.update(id="11111111-2222-3333-4444-555555555555", disabled=False, name="Updated OpenAI Key")
# Handle response
print(res)
```
### Parameters
| Parameter | Type | Required | Description | Example |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | *str* | :heavy_check_mark: | The BYOK credential ID (UUID). | 11111111-2222-3333-4444-555555555555 |
| `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/> | |
| `allowed_models` | List[*str*] | :heavy_minus_sign: | Optional allowlist of model slugs this credential may be used for. `null` means no restriction. | null |
| `allowed_user_ids` | List[*str*] | :heavy_minus_sign: | Optional allowlist of user IDs that may use this credential. `null` means no restriction. | null |
| `disabled` | *Optional[bool]* | :heavy_minus_sign: | Whether this credential is disabled. | false |
| `is_fallback` | *Optional[bool]* | :heavy_minus_sign: | Whether this credential is treated as a fallback — used only after non-fallback keys for the same provider have been tried. | false |
| `key` | *Optional[str]* | :heavy_minus_sign: | A new raw provider API key to rotate the credential in-place. The previous key material is overwritten and the masked label is regenerated. Encrypted at rest and never returned in API responses. | sk-proj-newkey456... |
| `name` | *OptionalNullable[str]* | :heavy_minus_sign: | Optional human-readable name for the credential. | Updated OpenAI Key |
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
### Response
**[components.UpdateBYOKKeyResponse](../../components/updatebyokkeyresponse.mdx)**
### Errors
| Error Type | Status Code | Content Type |
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |
Reference in New Issue View Git Blame Copy Permalink