# Passport Auth integration guide for AI coding agents

Use this guide to integrate Passport Auth into an application.

Passport Auth is a deploy-per-app auth service. It exposes hosted auth pages and public auth API endpoints under the same public web origin. The public API lives under `/api/v1/auth`.

Required integration input:
- Ask for `PASSPORT_AUTH_URL` before implementation. This is the self-hosted Passport Auth URL, for example `https://auth.example.com`.
- Use `PASSPORT_AUTH_URL` as the base URL for hosted pages and public API calls.
- Do not assume `passport.alactic.net` is the auth service URL; that domain hosts this documentation.

Core flow:
1. Configure the app origin and callback URL in the Passport Auth dashboard.
2. Generate a PKCE code verifier in the application.
3. Derive a SHA-256 base64url code challenge from the verifier.
4. Start auth by redirecting to a hosted page or calling the public API from custom auth screens.
5. Receive `?code=` on the app callback URL.
6. Exchange `{ code, code_verifier }` at `POST /api/v1/auth/token`.
7. Store the returned access token, refresh token, and user using the app's session model.
8. Use `GET /api/v1/auth/me` with `Authorization: Bearer <access_token>` for the current user.
9. Use `POST /api/v1/auth/refresh` to rotate refresh tokens.
10. Use `POST /api/v1/auth/logout` and clear local session state on logout.

Hosted pages:
- Open `${PASSPORT_AUTH_URL}/login?redirect_url=<encoded_callback>&code_challenge=<challenge>` for sign in.
- Open `${PASSPORT_AUTH_URL}/register?redirect_url=<encoded_callback>&code_challenge=<challenge>` for account creation.
- Hosted pages handle password, OTP, magic link, Google OAuth, and reset flows when those methods are enabled.
- The app callback receives only an authorization code, never tokens.

Custom pages:
- Call `POST /api/v1/auth/register` with `name`, `email`, `password`, `redirect_url`, and `code_challenge`.
- Then call `POST /api/v1/auth/register/verify` with `email` and `otp`.
- Call `POST /api/v1/auth/password/login` with `email`, `password`, `redirect_url`, and `code_challenge`.
- Call `POST /api/v1/auth/otp/start`, then `POST /api/v1/auth/otp/verify`.
- Call `POST /api/v1/auth/magic-link/start`; the email link should complete auth and return to the app callback.
- Call `GET /api/v1/auth/google/start?redirect_url=<callback>&code_challenge=<challenge>` and navigate to the returned `authorization_url`.

Token exchange:
```http
POST ${PASSPORT_AUTH_URL}/api/v1/auth/token
Content-Type: application/json

{
  "code": "authorization_code_from_callback",
  "code_verifier": "original_pkce_verifier"
}
```

Token response:
```json
{
  "access_token": "jwt",
  "refresh_token": "opaque_refresh_token",
  "token_type": "bearer",
  "expires_in": 7776000,
  "user": {
    "id": "user_id",
    "name": "Jane Appleseed",
    "email": "jane@example.com",
    "role": "user",
    "email_verified": true,
    "user_metadata": {}
  }
}
```

Important implementation rules:
- Keep the PKCE verifier client-side only until token exchange.
- Do not put access tokens or refresh tokens into redirect URLs.
- Validate missing or failed token exchange states and show a retry sign-in action.
- Store refresh tokens according to the app's security model.
- If using browser storage, prefer short-lived access-token memory storage plus refresh handling appropriate for the app.
- Always clear local tokens on logout.
- In production, redirect URLs must exactly match configured Passport Auth redirect URLs.
- In development, localhost and 127.0.0.1 URLs with ports are allowed when Passport Auth runs in development mode.

Public API reference:
- `GET /api/v1/auth/request/validate`
- `POST /api/v1/auth/register`
- `POST /api/v1/auth/register/verify`
- `POST /api/v1/auth/password/login`
- `POST /api/v1/auth/otp/start`
- `POST /api/v1/auth/otp/verify`
- `POST /api/v1/auth/magic-link/start`
- `POST /api/v1/auth/magic-link/consume`
- `POST /api/v1/auth/password-reset/start`
- `POST /api/v1/auth/password-reset/confirm`
- `GET /api/v1/auth/google/start`
- `GET /api/v1/auth/google/callback`
- `POST /api/v1/auth/token`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/auth/me`