OAuth

This page covers two flows that both require an AnyRouter account you already control: minting an additional key via PKCE, and the device authorization grant for browser-less apps. Neither is the right fit for "let anonymous users sign in with their own AnyRouter account and bill their own credits" — that's Sign in with AnyRouter, a separate open-registration OAuth 2.1 flow with no bearer key required to start.

Mint a key via PKCE

A lightweight flow so a trusted local tool (already holding one of your keys, e.g. a CLI or a dev server on localhost:3000) can generate a new scoped key without you copying it out of the dashboard by hand. Two endpoints drive it: create an authorization code, then exchange it for a new key. This is not an anonymous sign-in flow — both steps authenticate with an existing sk-ar-… key, so an app with no key cannot start it. Building "sign in with AnyRouter" for third-party users? Use the Sign in with AnyRouter guide instead.

The flow

sequenceDiagram
    participant App
    participant AnyRouter
    App->>App: Generate code_verifier + code_challenge (S256)
    App->>AnyRouter: POST /api/v1/auth/keys/code (challenge)
    AnyRouter-->>App: authorization code id
    App->>AnyRouter: POST /api/v1/keys (code + code_verifier)
    AnyRouter-->>App: new sk-ar-v1-… key (shown once)

{
  "data": {
    "id": "authcode_123",
    "app_id": 1,
    "created_at": "2026-04-24T00:00:00.000Z"
  }
}

{
  "key": "sk-ar-v1-actual-secret-only-shown-once",
  "user_id": "user_123"
}

Examples

curl https://anyrouter.dev/api/v1/auth/keys/code \
  -X POST \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com:443/callback",
    "code_challenge": "pkce_challenge_value",
    "code_challenge_method": "S256",
    "key_label": "oauth-app",
    "limit": 25,
    "usage_limit_type": "monthly"
  }'

curl https://anyrouter.dev/api/v1/keys \
  -X POST \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authcode_123",
    "code_verifier": "pkce_verifier_value",
    "code_challenge_method": "S256"
  }'

Device authorization

For apps that can't open a browser — a CLI, a terminal tool, a headless box — use the device authorization grant (RFC 8628). Your app shows the user a short code; the user approves it on any device with a browser; your app polls until the credential is ready.

Unlike the flow above, this one needs no existing API key: the user's approval in the browser is the authentication.

{ "error": "invalid_client", "error_description": "Unknown client_id" }

sequenceDiagram
    participant App
    participant User
    participant AnyRouter
    App->>AnyRouter: POST /api/v1/oauth/device/code
    AnyRouter-->>App: user_code + verification_uri
    App->>User: Show the code and the URL
    User->>AnyRouter: Open the URL, review permissions, approve
    loop every `interval` seconds
        App->>AnyRouter: POST /api/v1/oauth/token (device_code)
        AnyRouter-->>App: authorization_pending → access_token
    end

{
  "device_code": "8f2a…",
  "user_code": "K4RT-9WPZ",
  "verification_uri": "https://anyrouter.dev/cli/device",
  "verification_uri_complete": "https://anyrouter.dev/cli/device?code=K4RT-9WPZ",
  "expires_in": 600,
  "interval": 5
}

{
  "access_token": "sk-ar-v1-actual-secret-only-shown-once",
  "token_type": "Bearer",
  "scope": "inference read:credits",
  "user_id": "user_123"
}

curl https://anyrouter.dev/api/v1/oauth/device/code \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My CLI", "scope": "inference read:credits"}'

curl https://anyrouter.dev/api/v1/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=8f2a..."

Errors

Errors use the standard envelope:

{
  "error": {
    "code": "bad_request",
    "message": "callback_url is required",
    "metadata": {
      "type": "invalid_request_error"
    }
  }
}