handlers

Signature

type Handlers = {
  GET: (req: Request) => Response | Promise<Response>
  POST: (req: Request) => Response | Promise<Response>
  PATCH: (req: Request) => Response | Promise<Response>
  ALL: (req: Request) => Response | Promise<Response>
}

auth.handlers exposes the HTTP handlers that drive the OAuth 2.0 authorization and credentials sign-in flow. GET, POST, and PATCH are exported individually so you can mount them per-method; ALL is a unified handler that consolidates all three into a single entry point for routers that only accept one handler per route.

All routes below are relative to your configured basePath (default: /auth).

Endpoints

GET /auth/signIn/:oauth

Initiates the OAuth authorization flow, where :oauth is the id of the configured OAuth provider, either a built-in provider or a custom one. See OAuth Providers for the list of built-in providers and how to register custom ones.

Supports the redirect query parameters.

POST /auth/signIn/credentials

Signs in a user with a username and password. Expects a JSON payload:

{
  "username": "string",
  "password": "string"
}

Requires credentials.authorize to be configured, it validates the submitted credentials and returns the user profile used to create the session.

Supports the redirect query parameters.

GET /auth/session

Returns the current user's session as a JSON object containing the user's profile and the session expiration time. The session is created on sign-in and stored in a secure cookie.

export interface User {
  sub: string
  name?: string
  email?: string
  image?: string
}

export interface Session {
  user: User
  expires: string
}

The session response filters out JWT-standard claims (exp, iat, jti, nbf) and returns only user-facing profile data.

POST /auth/session

Updates session data from the initial OAuth profile, currently supports the email, name, and image fields, or any additional fields defined in identity.schema. For programmatic updates outside of a request/response cycle, use api.updateSession instead.

PATCH /auth/session

Updates the current user's session. The request body follows the shape defined by identity.schema; by default it supports email, name, and image:

{
  "user": {
    "name": "string",
    "email": "string",
    "image": "string"
  },
  "expires": "string"
}

Supports the redirect query parameters.

POST /auth/signUp

Registers a new user. No request body is required by default, though fields defined in signUp.schema may be included.

Requires signUp.onCreateUser to be configured, it creates the user record and returns the user profile used to create the session.

Supports the redirect query parameters.

GET /auth/callback/:oauth

Handles the OAuth provider callback after the user authorizes the request. :oauth must match the provider id used in the original GET /auth/signIn/:oauth call. Expects code and state query parameters to be present, as set by the provider.

For what happens internally between the initial redirect and a session being created (PKCE, state validation, token exchange), see OAuth Authorization Flow.

GET /auth/csrfToken

Returns a JSON object containing a CSRF token, used to protect state-changing requests (POST, PATCH) from cross-site request forgery. This token is required by POST /auth/signOut.

{
  "csrfToken": "string"
}

POST /auth/signOut

Signs out the current user and invalidates the session. Requires a signed CSRF token, submitted both as a cookie and as the X-CSRF-Token header, this is standard double-submit cookie CSRF protection:

new Request("/auth/signOut", {
  method: "POST",
  headers: {
    "X-CSRF-Token": "...",
    Cookie: "...",
  },
})

Supports the redirect query parameters.

Optional Query Parameters

Redirect

Any endpoint above marked "Supports the redirect query parameters" accepts redirect and redirectTo to control post-request navigation:

• redirect — "true" or "false". If true, the response redirects to redirectTo via the Location header. If false (default), the response is returned as JSON with no redirect.
• redirectTo — the URL to redirect to when redirect=true. Ignored otherwise. If omitted while redirect=true, the default post-action URL is used.