These four routes handle everything related to authentication. You’ll typically only interact with them through the UI, but the contracts are here if you need to build your own client.

GET /api/auth/start

File: app/api/auth/start/route.ts

Initiates the OAuth flow. Redirects to GitHub’s authorization page.

What happens

1. Generate CSRF: randomBase64Url(32) → 32 bytes, base64url
2. Create signed OAuth state JWT (HS256): payload is { type: "oauth", csrf, mode, returnTo }, expires in 10 minutes
3. Build GitHub auth URL: https://github.com/login/oauth/authorize?client_id=<id>&redirect_uri=/api/auth&scope=read:org+user:email&state=<jwt>&allow_signup=false
4. Set gh_auth_csrf cookie: httpOnly, secure, sameSite=none, path=/, maxAge=600
5. 302 redirect to GitHub

State token payload

interface OAuthState {
  type: 'oauth';
  csrf: string;
  mode: 'web' | 'mobile';
  returnTo: string;
}

Signed via lib/auth/state.ts (jose, HS256, keyed by authEnv.sessionSecret).

Cookie: gh_auth_csrf

httpOnly, secure, sameSite=none, path=/, maxAge=600. Random 32-byte base64url.

Edge cases

• Previous CSRF cookie gets overwritten each call. That’s fine — the old state JWT would have a mismatch anyway.
• If AUTH_SESSION_SECRET is missing, falls back to a hash of GITHUB_CLIENT_SECRET:GITHUB_APP_ID.
• Very long returnTo values are embedded in the JWT (~8KB limit), but the browser URL might truncate on redirect.

GET /api/auth

File: app/api/auth/route.ts

The OAuth callback. GitHub redirects here after the user authorizes the app.

What happens

1. Verify state JWT: check HS256 signature, expiry, read csrf/mode/returnTo
2. If state.type === "install": redirect to /api/install/callback (handles install callbacks that land here)
3. CSRF check: gh_auth_csrf cookie must exist and match state.csrf. Fail → 403
4. Exchange code: POST https://github.com/login/oauth/access_token with Accept: application/json. Gets back access_token, token_type, scope, optionally expires_in / refresh_token. Fail if error field in response.
5. Encrypt the access token using AES-256-GCM (lib/auth/server/crypto.ts): produces encrypted, iv, tag
6. Fetch viewer profile (lib/auth/server/oauth.ts): octokit.graphql ViewerProfile query → id, login, name, avatar, orgs (paginated). Falls back to REST if GraphQL fails.
7. Discover installations (lib/auth/server/installation-service.ts:listOrgInstallations): paginate GET /user/installations, filter to account_type === 'organization', return installation IDs.
8. Upsert normalized user data (lib/auth/server/user-service.ts):
   • upsertUser() — insert or update users table
   • upsertOrganizations() — insert or update organizations table
   • upsertMemberships() — insert or update organization_memberships table
9. Sync installations (lib/auth/server/installation-service.ts:syncInstallations): upsert each org installation into github_installations table.
10. Create session (lib/auth/server/session.ts:createSession):
    • 64-char hex session ID via crypto.randomBytes(32).toString('hex')
    • Insert into auth_sessions with user_id (FK), encrypted token
    • Insert session-installation links into session_installations join table
    • Expiry: 24 hours default
11. Set gh_session cookie (httpOnly, sameSite=lax, secure, maxAge=remaining seconds) + delete gh_auth_csrf cookie
12. 302 redirect to returnTo

Response (web)

302 Redirect to returnTo with gh_session cookie set.

Response (mobile/JSON)

When mode=mobile:

{
  "sessionToken": "sess_abc123...",
  "session": {
    "id": "sess_abc123...",
    "user": {
      "id": 12345,
      "login": "octocat",
      "name": "Octocat",
      "avatarUrl": "https://avatars.githubusercontent.com/u/12345",
      "organizations": [
        {
          "id": 67890,
          "login": "my-org",
          "name": "My Org",
          "avatarUrl": "...",
          "viewerCanAdminister": true
        }
      ]
    },
    "installationIds": [456, 789],
    "expiresAt": "2026-05-26T12:00:00.000Z"
  }
}

gh_auth_csrf is deleted in both modes.

Error responses

All web-mode errors redirect to returnTo with ?authError=<message>.

Edge cases

• Expired state JWT (>10 min): jwtVerify throws → 400. Retry.
• Reused auth code: GitHub returns error on exchange → 500.
• No org access: session created with empty organizations array. Auth works, org features blocked.
• No installations: session created with installationIds: []. Must install app.
• State cookie missing (privacy mode): CSRF check fails → 403.

GET /api/auth/session

File: app/api/auth/session/route.ts

Reads the current session. Session ID comes from (in order):

1. Authorization: Bearer <sessionId> (mobile/API)
2. gh_session cookie (web)

Both are handled by getRequestSession() (lib/auth/request-session.ts) → getSession() → Supabase lookup with joins. Expired sessions are auto-deleted.

Token refresh

If githubAccessTokenExpiresAt is set and within 5 minutes of expiry:

1. Calls refreshGitHubToken() (lib/auth/server/token-refresh.ts)
2. If refreshed: encrypts new token, updates auth_sessions row
3. If expired (no valid refresh token): returns 401

Response (authenticated)

{
  "authenticated": true,
  "session": {
    "id": "sess_abc123...",
    "user": {
      "id": 12345,
      "login": "octocat",
      "name": "Octocat",
      "avatarUrl": "https://avatars.githubusercontent.com/u/12345",
      "organizations": [...]
    },
    "installationIds": [456, 789],
    "expiresAt": "2026-05-26T12:00:00.000Z"
  }
}

The SessionView type (types/auth/session.ts) intentionally omits githubToken.

Response (unauthenticated) — 401

{ "authenticated": false, "session": null }

Frontend consumption

useAuthSession() hook (hooks/use-auth-session.ts): React Query, staleTime=0, retry=false. Data synced into useAuthStore (Zustand).

Edge cases

• Session expires between check and render: authenticated: false. ProtectedRoute catches and redirects to /api/auth/start.
• Supabase transient error: getSession() returns null → 401. Handled by refetchOnMount: 'always' + refetchOnReconnect: true.
• Rapid page loads: React Query deduplicates within staleTime.

POST /api/auth/logout

File: app/api/auth/logout/route.ts

No body required. Session from gh_session cookie or Authorization header.

{ "ok": true }

What happens

1. getRequestSession(request) → read session
2. If it exists, deleteSession(session.id) from Supabase
3. Delete cookies: gh_session, gh_auth_csrf, gh_install_csrf

Frontend logout (Header.tsx)

1. POST /api/auth/logout
2. Toast “Signed out successfully”
3. setSession(null) in Zustand
4. Update + invalidate React Query ['auth-session']
5. Remove ['install-status'] query
6. Redirect to /

Edge cases

• No session: delete is a no-op. Still clears cookies and returns { ok: true }.
• Supabase delete fails: fire-and-forget. Cookies still cleared.
• Cookie clearing blocked: session ID already deleted from Supabase — cookies are inert.

Implementation architecture

Module map

Session data flow

GitHub OAuth → exchangeOAuthCode()
                    ↓
            encrypt() token
                    ↓
            getViewerProfile() → orgs
                    ↓
            UserService.upsertUser()
            UserService.upsertOrganizations()
            UserService.upsertMemberships()
                    ↓
            InstallationService.syncInstallations()
                    ↓
            createSession() → auth_sessions table
                    ↓
            Set gh_session cookie

Related

• Install Routes — GitHub App installation flow
• Webhook — GitHub App webhook handler
• Organization Routes — org list and detail
• Security Model — cookies, CSRF, encryption
• Database Schema — auth_sessions, users, organizations tables