Authentication Usage

The generated auth server exposes a small set of functions from server/auth:

import {
  auth,
  currentUser,
  handlers,
  signIn,
  signOut,
  verifyAccessToken,
} from '@/server/auth'

The handlers function is the HTTP entry point. The other functions are server helpers that can be used directly inside server-side application code.

Route handlingCopy Anchor Link

The auth handler expects requests under /api/auth/*.

GET routesCopy Anchor Link

POST routesCopy Anchor Link

The handler also responds to OPTIONS with 204 and returns 405 for unsupported methods.

Router integrationCopy Anchor Link

The handler accepts a standard Request and returns a standard Response, so it can be mounted from frameworks that expose Web Fetch-compatible handlers.

import { handlers } from '@/server/auth'

export async function GET(request: Request) {
  return handlers(request)
}

export async function POST(request: Request) {
  return handlers(request)
}

Use framework-specific request adapters when the framework does not expose a native Request.

Authentication helpersCopy Anchor Link

authCopy Anchor Link

auth({ headers }) resolves the refresh token from the configured cookie or a Bearer authorization header. It validates the hashed refresh secret and refreshes the session expiry when it is inside expiresThreshold.

const session = await auth({
  headers: request.headers,
})

The returned value has token, user, and expiresAt.

currentUserCopy Anchor Link

currentUser({ headers }) reads the access token, verifies the JWT, and loads the user through the adapter.

const user = await currentUser({
  headers: request.headers,
})

verifyAccessTokenCopy Anchor Link

const payload = await verifyAccessToken(accessToken)

if (!payload) {
  // invalid or expired token
}

The result is { userId } or null.

Credentials sign-inCopy Anchor Link

The password flow looks up a credentials account by email and verifies its stored password hash.

const session = await signIn({
  email,
  password,
})

The returned object contains an access token, refresh token, and session expiry.

OAuth flowCopy Anchor Link

A provider request starts at:

GET /api/auth/google

The server:

1. Generates a random state and PKCE verifier.
2. Stores them in short-lived cookies.
3. Redirects to the provider.
4. Verifies the returned state.
5. Exchanges the code for provider data.
6. Looks up the provider account or email.
7. Creates the user/account when necessary.
8. Creates a local session and redirects back.

The providers that support PKCE use S256 code challenges. Facebook uses the non-PKCE flow implemented by its provider.

Session configurationCopy Anchor Link

The default configuration in the registry is:

session: {
  expiresIn: 60 * 60 * 24 * 7,
  expiresThreshold: 60 * 60 * 24,
  accessTokenExpiresIn: 60 * 15,
}

These values are examples, not mandatory production defaults. Set a strong AUTH_SECRET and choose lifetimes appropriate for your application.

Client sessionCopy Anchor Link

SessionProvider uses React Query to fetch /api/auth/current-user.

import { SessionProvider, useSession } from '@/hooks/use-session'

function Providers({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>
}

function AccountButton() {
  const session = useSession()

  if (session.status === 'loading') return <span>Loading...</span>
  if (session.status === 'unauthenticated') return <button>Sign in</button>

  return <span>{session.session.user.email}</span>
}

The provider also exposes signIn, signOut, and refreshToken. Successful mutations invalidate or update the current-user query.

API ReferenceCopy Anchor Link

createAuth(config)Copy Anchor Link

Returns:

{
  auth,
  currentUser,
  verifyAccessToken,
  signIn,
  signOut,
  handlers,
}

AuthConfigCopy Anchor Link

interface AuthConfig {
  secret: string
  adapter: AuthAdapter
  providers: BaseProvider[]
  session: {
    expiresIn: number
    expiresThreshold: number
    accessTokenExpiresIn: number
  }
  cookies: {
    keys: {
      accessToken: string
      refreshToken: string
      state: string
      codeVerifier: string
      redirectUri: string
    }
    options: {
      Path: string
      HttpOnly: boolean
      Secure: boolean
      SameSite: 'Lax' | 'Strict' | 'None'
      Domain?: string
      Expires?: Date | string
      'Max-Age'?: number
    }
  }
}

SessionProviderCopy Anchor Link

{
  children: React.ReactNode
}

useSessionCopy Anchor Link

Returns the current session state together with:

signIn(opts: { email: string; password: string })
signOut()
refreshToken()