Skip to main content
Use OAuth to let your users bring their own OpenRouter API key to your app. Each user signs in to OpenRouter and authorizes your app, and your app receives an API key tied to their account. Their requests are billed to their own OpenRouter credits, so you don’t pay for their inference or manage keys on their behalf. The flow uses Proof Key for Code Exchange (PKCE), so users connect in one click and your app never handles their OpenRouter password. Here’s a step-by-step guide:

PKCE Guide

Step 1: Send your user to OpenRouter

To start the PKCE flow, generate a random code_verifier, derive a code_challenge from it, and send your user to OpenRouter’s /auth URL with a callback_url parameter pointing back to your site:
Authorization URL
The code_challenge and code_challenge_method parameters are required. Set code_challenge_method to S256 and code_challenge to the base64url encoding of the SHA-256 hash of code_verifier (Auth0’s PKCE docs).
Why PKCE is mandatoryThe authorization code in the callback URL can be exchanged for an API key on your user’s account. Without PKCE, anyone who obtains the code before your app exchanges it gets that key. Codes leak through browser history and sync, extensions that can read URLs, proxy and server logs, and other apps registered for the same custom scheme. An attacker with the key can spend your user’s credits until the user notices and revokes it.With PKCE, the code is useless on its own. Only your app holds the code_verifier, and OpenRouter refuses to exchange the code without it.
Your user will be prompted to log in to OpenRouter and authorize your app. After authorization, they will be redirected back to your site with a code parameter in the URL:
Alt text

How to Generate a Code Challenge

Generate a new code_verifier for every authorization request and keep it until the user returns to your callback, for example in sessionStorage or your server-side session. Never put it in a URL. The following example uses the Web Crypto API and the Buffer API to generate a code challenge for the S256 method. You will need a bundler to use the Buffer API in the web browser:
Use an https:// callback URL for hosted apps. PKCE stops a stolen code from being exchanged, but it cannot protect a page served over plain HTTP.

Localhost Apps

Localhost callbacks are supported on any port. This is useful for CLI tools and local-first apps that bind to an arbitrary free OS port for the OAuth callback (e.g. http://localhost:51423/callback).
Localhost apps are assigned a fixed title matching the host and port (e.g. localhost:3000) but will not appear in the OpenRouter marketplace or rankings. If you want a custom app name and marketplace presence, use a public URL as the callback instead.
When moving to production, replace the localhost callback URL with a public URL (your project website or a GitHub repo link) to get full app attribution.

Headless Apps (SSH Servers, Containers)

If your app runs where a localhost callback can’t be reached (an SSH session, a remote dev box, a container), omit callback_url entirely:
Headless (No Callback)
After the user authorizes, the page displays the authorization code on screen instead of redirecting. The user copies it and pastes it into your app (e.g. at a terminal prompt), and you exchange it in Step 2 exactly as usual. The code is single-use and expires after 10 minutes.

Optional Parameters

If both workspace_id and required_workspace_id are present, required_workspace_id takes precedence. Use workspace_id to suggest a workspace and required_workspace_id to enforce one (for example, an internal onboarding flow that must mint keys into a specific team workspace). Workspace IDs are validated server-side against the account the user authorizes with. A workspace the user cannot access is rejected, regardless of what the URL asked for.

Step 2: Exchange the code for a user-controlled API key

After the user logs in with OpenRouter, they are redirected back to your site with a code parameter in the URL:
Alt text
Extract this code using the browser API:
Then use it to make an API call to https://openrouter.ai/api/v1/auth/keys to exchange the code for a user-controlled API key:
Once you have the API key, you can create links to the user’s OpenRouter activity and key settings pages by hashing the key with SHA-256. Use the lowercase hexadecimal digest in both URLs:
The links only work for the signed-in owner of the API key. If the hash does not resolve for the viewer, the page returns a 404 rather than showing unfiltered data. And that’s it for the PKCE flow!

Step 3: Use the API key

Use the API key to make OpenRouter requests. It is a secret that can spend the user’s credits until they revoke it. Store it encrypted in a server-side database, or in the OS keychain on desktop and mobile. Never persist it in browser-side storage such as localStorage, sessionStorage, IndexedDB, or cookies readable by JavaScript: any script running on your origin can read them. Keep it out of URLs and logs.

Error Codes

  • 400 Invalid code_challenge_method: Make sure you’re using the same code challenge method in step 1 as in step 2.
  • 403 Invalid code or code_verifier: Make sure your user is logged in to OpenRouter, and that code_verifier and code_challenge_method are correct.
  • 403 Authorization code expired: Authorization codes expire 10 minutes after issuance. Restart the OAuth flow and exchange the new code promptly.
  • 405 Method Not Allowed: Make sure you’re using POST and HTTPS for your request.

External Tools