Authentication

All API requests to Passage require authentication. Two auth paths are supported — both resolve to an org (the top-level tenant).

Auth paths

Path	Used by	Token format
API key (machine identity)	Developer backends, CI/CD, scripts	`Authorization: Bearer psg_xxx`
OAuth 2.0 (human identity)	Dashboard, MCP server, CLI	`Authorization: Bearer <JWT>`

Platform middleware detects the path by token prefix: psg_* → API key lookup, otherwise → JWT signature verification. Downstream routes don’t care which was used — both resolve to an orgId.

API keys

API keys are scoped to an org and grant access to all resources owned by that org.


Authorization: Bearer psg_xxx

Keys are created and managed via the org management API or the dashboard
Each org can have multiple active keys
Keys can be revoked without affecting other keys
Keys can optionally have an expiration date

OAuth 2.0 (JWT)

For interactive clients (dashboard, MCP, CLI), Platform acts as an OAuth 2.0 Authorization Server with PKCE.

Flow:

Client redirects to GET /auth/authorize on Platform
User logs in via magic link email
Platform redirects back with an authorization code
Client exchanges code + PKCE verifier for access token (JWT) + refresh token
Client sends Authorization: Bearer <JWT> on all requests

Discovery: GET /.well-known/oauth-authorization-server returns RFC 8414 metadata.

Token format:

Access token: short-lived ES256 JWT (~1h). Claims: { sub, email, orgs: [{ id, role }] }
Refresh token: opaque (prt_*), stored in D1, long-lived (~30d)

All interactive clients are public clients — PKCE is required, no client_secret.

Roles

Org members have one of three roles:

Role	Permissions
admin	Full access — manage members, API keys, create sessions, view everything
member	Create sessions, view sessions, use MCP tools. No member/key management
viewer	Read-only — view sessions and events. No session creation or management

API keys grant full access to the org’s resources (equivalent to admin for data access).

Public endpoints

Some endpoints do not require authentication:

POST /link/claim — Used by the client SDK to claim a link
POST /webhook_verification_key/get — Fetch the public key for webhook verification
GET /.well-known/oauth-authorization-server — OAuth discovery metadata
POST /auth/register — Self-serve signup
POST /auth/magic-link — Send login magic link
GET /auth/callback — Redeem magic link
POST /auth/token — Exchange code or refresh token
GET /auth/jwks — Public signing key (JWKS)

Next steps

Connect Quickstart — Get started with account linking
Platform Quickstart — Get started with session control
Org Management API — Manage orgs, members, and API keys