PKCE Guide
Step 1: Send your user to OpenRouter
To start the PKCE flow, generate a randomcode_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
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).
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:

How to Generate a Code Challenge
Generate a newcode_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.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), omitcallback_url entirely:
Headless (No Callback)
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).
If limit or expiration is missing or invalid, the form uses its default for that field, and the other parameter still applies. The defaults are no credit limit and no expiry.
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 acode parameter in the URL:

https://openrouter.ai/api/v1/auth/keys to exchange the code for a user-controlled API key:
Deep-link to the user’s 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: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 aslocalStorage, 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 thatcode_verifierandcode_challenge_methodare 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 usingPOSTandHTTPSfor your request.