Passport Auth
Documentation

Use Passport Auth

Passport Auth can be integrated with hosted auth pages or with custom app screens. Both modes use the same PKCE authorization-code flow and the same public auth API.

How it works

1 Start auth

Your app creates a PKCE verifier and challenge, then opens a hosted page or calls a public API endpoint.

2 Receive code

Passport Auth verifies the user and sends an authorization code to your configured callback URL.

3 Exchange tokens

Your app exchanges the code and verifier for an access token, refresh token, and user object.

Tokens never go in redirect URLs.

Redirects only carry short-lived authorization codes. Your app performs the token exchange from the callback route.

Configure URLs

Every app needs the self-hosted Passport Auth URL for the deployed auth service, such as https://auth.example.com. Use that URL as the base for hosted pages and public API calls. In the Passport Auth dashboard, set your application domain, allowed origins, and redirect URLs. Allowed origins control browser CORS. Redirect URLs control where auth codes are allowed to return. 

Application domain: https://app.example.com
Passport Auth URL: https://auth.example.com
Allowed origins:    https://app.example.com
Redirect URLs:      https://app.example.com/auth/callback

Hosted pages integration

Hosted pages are the fastest path. Your app redirects the browser to Passport Auth and lets the auth service render login, registration, OTP, magic link, reset, and Google OAuth screens. 

GET https://auth.example.com/login?redirect_url=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&code_challenge=S256_challenge
/login

Password login, Google OAuth, OTP, magic link, reset, and create-account links.

/register

Name, email, password, then email verification via OTP.

/verify

OTP verification and magic-link consumption.

/reset-password

Password reset OTP flow.

Custom pages integration

Build your own login and registration UI when you need full product control. Your screens call the public API directly and still use the same redirect_url and code_challenge. 

POST https://auth.example.com/api/v1/auth/password/login
{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple",
  "redirect_url": "https://app.example.com/auth/callback",
  "code_challenge": "S256_challenge"
}

Use API Reference for exact inputs and outputs for password, OTP, magic link, Google OAuth, token refresh, logout, and /me.

Callback exchange

Your callback route receives ?code=. Read the original PKCE verifier from your app session or local storage, exchange it, then store the returned tokens using your normal app session model. 

POST https://auth.example.com/api/v1/auth/token
{
  "code": "code_from_callback_query",
  "code_verifier": "original_pkce_verifier"
}

Sessions and current user

Use the access token with GET /api/v1/auth/me. When it expires, rotate the refresh token with POST /api/v1/auth/refresh. On logout, revoke the refresh token with POST /api/v1/auth/logout. 

GET /api/v1/auth/me
Authorization: Bearer public_access_token

Email and Google OAuth

Configure Resend for OTP, magic-link, password-reset, and admin-invite delivery. Configure Google OAuth in Settings; Passport Auth shows the exact JavaScript origin and callback URI to paste into Google Cloud.

Local development

Development mode still validates CORS and redirects, but permits localhost and 127.0.0.1 URLs with ports. This keeps local apps honest without forcing HTTPS during development. 

Allowed origins: http://localhost:5173
Redirect URLs:   http://localhost:5173/auth/callback