Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Auth Flow Visualizer

Interactive diagrams showing how authentication flows work in Aero2.

Authorization Code Flow

The standard flow for authenticating users in your application:

Browser
Your App
Aero2
  1. 1
    Browser → Your App
    User clicks Login
  2. 2
    Your App
    Generate PKCE code_verifier + code_challenge
    crypto.getRandomValues() + SHA-256
  3. 3
    Your App → Aero2
    Redirect to /oauth2/authorize
    ?client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&response_type=code&scope=openid+profile+email
  4. 4
    Aero2 → Browser
    Show login page
    User authenticates with identity provider
  5. 5
    Aero2 → Your App
    Redirect to redirect_uri with code
    ?code=abc123&state=xyz
  6. 6
    Your App → Aero2
    Exchange code for tokens
    POST /oauth2/token grant_type=authorization_code&code=...&code_verifier=...
  7. 7
    Aero2 → Your App
    Return access_token, id_token, refresh_token
    RS256-signed JWTs
  8. 8
    Your App → Aero2
    Fetch user info (optional)
    GET /oauth2/userinfo Authorization: Bearer <access_token>

Relying Party Flow

How Aero2 delegates authentication to external providers (GitHub, Google, etc.):

Browser
Aero2
External IdP
  1. 1
    Browser → Aero2
    User clicks Login with GitHub
    GET /rp/authorize?idp=github&redirect_uri=/dashboard
  2. 2
    Aero2
    Generate state, store in DB
    10-minute expiry, set HttpOnly cookie
  3. 3
    Aero2 → External IdP
    Redirect to GitHub authorize URL
    ?client_id=...&redirect_uri=/rp/callback/github&state=...
  4. 4
    External IdP → Browser
    User authenticates with GitHub
  5. 5
    External IdP → Aero2
    Redirect back with code
    GET /rp/callback/github?code=...&state=...
  6. 6
    Aero2
    Validate state (cookie + DB)
    Atomic DELETE with RETURNING prevents replay
  7. 7
    Aero2 → External IdP
    Exchange code for access token
    POST to GitHub token endpoint
  8. 8
    Aero2 → External IdP
    Fetch user info from GitHub
    GET /user with access token
  9. 9
    Aero2
    Create/link local user, create session
  10. 10
    Aero2 → Browser
    Set session cookie, redirect to dashboard
    HttpOnly, Secure, SameSite=Lax

Refresh Token Flow

How your application obtains new access tokens using a refresh token:

Your App
Aero2
  1. 1
    Your App
    Access token expires
    1-hour lifetime
  2. 2
    Your App → Aero2
    Request new tokens
    POST /oauth2/token grant_type=refresh_token&refresh_token=...
  3. 3
    Aero2
    Validate and rotate refresh token
    Old token invalidated, new token issued
  4. 4
    Aero2 → Your App
    Return new access_token + refresh_token
    New refresh token replaces the old one

See Also