OAuth PKCE

Register OAuth apps and implement PKCE authorization flows.

Overview

BrainstormRouter supports OAuth 2.0 with PKCE for third-party integrations. Register an OAuth app, redirect users for consent, and receive a scoped API key.

Developer endpoints (API Key auth)

Method	Path	Auth	Description
POST	/v1/oauth/apps	API Key	Register an OAuth app
GET	/v1/oauth/apps	API Key	List your apps
DELETE	/v1/oauth/apps/:id	API Key	Delete an app

User endpoints (JWT auth)

Method	Path	Auth	Description
GET	/auth/oauth/authorize	None	Get app info for consent
POST	/auth/oauth/authorize	JWT	Issue auth code
POST	/auth/oauth/token	None	Exchange code for API key

Register an app

curl -X POST https://api.brainstormrouter.com/v1/oauth/apps \
  -H "Authorization: Bearer br_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "callback_urls": ["https://myapp.com/callback"],
    "scopes": ["completions", "memory"]
  }'

Available scopes

Scope	Access
completions	Chat completions
models	Model listing
memory	Memory read/write
embeddings	Embeddings API
usage	Usage analytics
full	Everything

Authorization flow

1. Redirect user to BrainstormRouter with PKCE challenge:

GET /auth/oauth/authorize?client_id=br_app_...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&scope=completions+memory

1. User approves → redirect back with authorization code

1. Exchange code for API key:

curl -X POST https://api.brainstormrouter.com/auth/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "code": "auth-code",
       "redirect_uri": "https://myapp.com/callback",
       "code_verifier": "original-verifier",
       "client_id": "br_app_..."
     }'

1. Receive a scoped API key (90-day expiry):

{
     "key": "br_live_...",
     "scopes": ["completions", "memory"],
     "expires_at": "2025-05-20T00:00:00.000Z"
   }