Request lifecycle

Auth.ServeHTTP dispatches a fixed action table — the same routes Auth.js core exposes, plus token refresh and MFA.

Route table

Mount the handler at BasePath (default /auth):

mux.Handle("/auth/", auth)

Method	Path	Handler
GET	/auth/session	Current session JSON
GET	/auth/csrf	CSRF token
GET	/auth/providers	Public provider metadata
GET/POST	/auth/signin	List providers or custom page redirect
GET/POST	/auth/signin/:provider	Start provider flow
GET/POST	/auth/callback/:provider	Complete sign-in
POST	/auth/signout	Clear session
POST	/auth/token	Refresh bearer tokens
POST	/auth/mfa/verify	Complete MFA after credentials
GET	/auth/sessions	List sessions (database strategy)
DELETE	/auth/sessions?token=…	Revoke one session

OAuth sign-in sequence

sequenceDiagram
    participant C as Client
    participant G as goauth
    participant P as Provider (GitHub)

    C->>G: GET /auth/signin/github
    G->>G: PKCE + state cookies
    G->>C: 302 authorize URL
    C->>P: User logs in
    P->>C: 302 /auth/callback/github?code&state
    C->>G: GET callback
    G->>P: Exchange code for tokens
    G->>P: Fetch user profile
    G->>G: Callbacks.SignIn, resolveUser, session
    G->>C: Set-Cookie + redirect

Credentials + MFA sequence

When MFA.Enabled is true, credentials sign-in is two steps:

sequenceDiagram
    participant C as Client
    participant G as goauth

    C->>G: POST /auth/callback/credentials
    G->>G: Authorize OK, device not trusted
    G->>C: 200 { challenge, expiresIn }
    Note over G: SendCode(email, OTP)
    C->>G: POST /auth/mfa/verify challenge+code
    G->>C: Session cookie or tokens

Passkey sequence

sequenceDiagram
    participant C as Browser
    participant G as goauth

    C->>G: POST /auth/signin/passkey
    G->>C: WebAuthn request options (JSON)
    C->>C: navigator.credentials.get()
    C->>G: POST /auth/callback/passkey (credential JSON)
    G->>G: Verify assertion, update counter
    G->>C: Session established

GetSession resolution order

auth.GetSession(w, r) checks, in order:

1. Authorization: Bearer access token (if Tokens.Enabled)
2. Session cookie (JWT or database session token)
3. Returns nil, nil when unauthenticated (not an error)

Error responses

Errors use structured JSON with a kind field. See Errors reference.