openrouter-python-sdk-retry-errors/docs/sdks/oauth/README.md

OAuth

Overview

OAuth authentication endpoints

Available Operations

• exchange_auth_code_for_api_key - Exchange authorization code for API key
• create_auth_code - Create authorization code

exchange_auth_code_for_api_key

Exchange an authorization code from the PKCE flow for a user-controlled API key

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.o_auth.exchange_auth_code_for_api_key(code="auth_code_abc123def456", code_challenge_method="S256", code_verifier="dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
code	str	✔️	The authorization code received from the OAuth redirect	auth_code_abc123def456
http_referer	Optional[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_title	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter's dashboard.
x_open_router_categories	Optional[str]	➖	Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
code_challenge_method	OptionalNullable[operations.ExchangeAuthCodeForAPIKeyCodeChallengeMethod]	➖	The method used to generate the code challenge	S256
code_verifier	Optional[str]	➖	The code verifier if code_challenge was used in the authorization request	dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.ExchangeAuthCodeForAPIKeyResponse

Errors

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

create_auth_code

Create an authorization code for the PKCE flow to generate a user-controlled API key

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.o_auth.create_auth_code(callback_url="https://myapp.com/auth/callback", code_challenge="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", code_challenge_method="S256", limit=100)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
callback_url	str	✔️	The callback URL to redirect to after authorization. Supports https URLs and localhost/127.0.0.1 URLs on any port for local CLI tools.	https://myapp.com/auth/callback
http_referer	Optional[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_title	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter's dashboard.
x_open_router_categories	Optional[str]	➖	Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.
code_challenge	Optional[str]	➖	PKCE code challenge for enhanced security	E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
code_challenge_method	Optional[operations.CreateAuthKeysCodeCodeChallengeMethod]	➖	The method used to generate the code challenge	S256
expires_at	date	➖	Optional expiration time for the API key to be created	2027-12-31T23:59:59Z
key_label	Optional[str]	➖	Optional custom label for the API key. Defaults to the app name if not provided.	My Custom Key
limit	Optional[float]	➖	Credit limit for the API key to be created	100
usage_limit_type	Optional[operations.UsageLimitType]	➖	Optional credit limit reset interval. When set, the credit limit resets on this interval.	monthly
workspace_id	Optional[str]	➖	Optional workspace ID to associate the API key with
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.CreateAuthKeysCodeResponse

Errors

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