# OAuth PKCE

> Let users connect their AnyRouter account in one click and hand your app their own API key, using the same PKCE flow as OpenRouter.


# OAuth PKCE

Let users connect to AnyRouter with [PKCE](https://oauth.net/2/pkce/): they approve once and your app receives an API key that belongs to them, billed to their account. It is compatible with OpenRouter's PKCE flow and needs no client registration or secret, so it works in browser-only apps and CLIs. For a registered app with a "Sign in with AnyRouter" button and revocable tokens, see [Sign in with AnyRouter](/guides/sign-in-with-anyrouter).

## Flow

::::steps

:::step{title="Send the user to /auth"}
```txt
https://anyrouter.dev/auth?callback_url=<YOUR_SITE_URL>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256
```

For S256, `code_challenge` is the base64url SHA-256 of your `code_verifier`, a random 43 to 128 character string (letters, digits, `-`, `.`, `_`, `~`). Keep the verifier in your app, never in the URL. The challenge is optional with a `callback_url` but recommended; without it the code is protected only by delivery to your callback.

After the user approves, AnyRouter redirects to your `callback_url` with `?code=...` (an existing query string is kept). If they deny, you get `?error=access_denied`.
:::

:::step{title="Exchange the code for a key"}
`POST https://anyrouter.dev/api/v1/auth/keys`, no `Authorization` header. Codes are single-use and expire after 10 minutes.

```js
const response = await fetch("https://anyrouter.dev/api/v1/auth/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code: "<CODE_FROM_QUERY_PARAM>",
    code_verifier: "<CODE_VERIFIER>", // required if you sent a challenge
    code_challenge_method: "S256", // must match step 1
  }),
})
const { key, user_id } = await response.json()
// { "key": "sk-ar-v1-...", "user_id": "user_123" }  (key is shown once)
```
:::

:::step{title="Use the key"}
Store it per user and send it as `Authorization: Bearer <key>` to `https://anyrouter.dev/api/v1/chat/completions` or any other endpoint.
:::

::::

Generating the S256 challenge in the browser:

```js
const b64url = (b) => btoa(String.fromCharCode(...new Uint8Array(b)))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32))) // 43 chars
const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)))
```

Keep `verifier` (for example in `sessionStorage`) until the user returns. Never log or display the returned key.

## Localhost and headless apps

- Localhost callbacks work on any port (`http://localhost:51423/callback`, `http://127.0.0.1`, `http://[::1]`). Every other callback must use `https`. The consent card and key are named after the callback host and port.
- Where no callback is reachable (SSH, containers), omit `callback_url`. The page shows the code on screen for the user to paste into your app. A `code_challenge` is **required** in this mode.

## Optional parameters

They prefill the consent form; the user can change them.

| Parameter | Effect |
|---|---|
| `callback_url` | Where to send the user after approval. Omit for headless mode. |
| `code_challenge` | PKCE challenge. Required when `callback_url` is omitted. |
| `code_challenge_method` | `S256` or `plain`. Defaults to `plain` when a challenge is sent without a method. |
| `key_label` | Name of the key that will be created. |
| `workspace_id` | Preselects the workspace for the new key. |
| `required_workspace_id` | Locks the key to this workspace; the user cannot approve if not a member. Overrides `workspace_id`. |
| `limit` | Spend limit for the key, in USD. |
| `usage_limit_type` | Limit reset period: `daily`, `weekly` or `monthly`. |
| `expires_at` | Key expiry, ISO 8601 timestamp in the future. |

Workspaces are checked against the signed-in user's memberships.

## Errors

| Status | Message | Cause |
|---|---|---|
| 400 | `Invalid code_challenge_method` | Does not match the method used in step 1. |
| 403 | `Invalid code or code_verifier` | Code unknown or already used, or verifier missing or wrong. |
| 403 | `Authorization code expired` | More than 10 minutes since approval. Restart at step 1. |
| 405 | `Method Not Allowed` | The exchange accepts `POST` only. |

Other malformed requests, such as a missing `code`, return `400`.

## Revoking keys

The key shows on the user's [Keys page](https://anyrouter.dev/dashboard/keys) under your app's name, and revoking it there stops it immediately. Any limit or expiry set on the consent card applies. On a `401`, send the user through the flow again.

## Migrating from OpenRouter

Swap `openrouter.ai` for `anyrouter.dev` in the authorize URL (`/auth`), the exchange (`/api/v1/auth/keys`) and inference URLs. Parameters, response shape and errors match. AnyRouter also returns `user_id` and adds `limit`, `usage_limit_type` and `expires_at`.

## Linking users to a key

Deep-link users to the key you created using the lowercase hex SHA-256 of the key string:

| Link | Lands on |
|---|---|
| `https://anyrouter.dev/keys/<SHA256_OF_KEY>` | The key's page |
| `https://anyrouter.dev/logs?api_key_hash=<SHA256_OF_KEY>` | Request logs filtered to that key |

```js
const hashHex = Array.from(
  new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key))),
).map((b) => b.toString(16).padStart(2, "0")).join("")
```

Links resolve only inside the owning account; otherwise the page returns **404**. Add `?org=<workspace_id>` to the logs link when the key lives in a workspace.


## Related

- [Sign in with AnyRouter](/docs/guides/sign-in-with-anyrouter.md)
- [OAuth](/docs/api-reference/oauth.md)
- [Migrate from OpenRouter](/docs/guides/migrate-from-openrouter.md)
- [Chat Completions API](/docs/api-reference/chat-completions.md)
