Session management

How to use a session

Client-side

Use the useSession hook from createClientSideAuth to get a React Query result. Read the current SessionState from its data field. The hook calls the session API route, typically /api/auth/session.

Use your configured auth exports and render within the providers from your router's setup guide:

"use client";

import { useSession } from "@/lib/auth/client";

export function SessionStatus() {
  const { data: session } = useSession();

  return <p>{session.isAuthenticated ? "Signed in" : "Signed out"}</p>;
}

Server-side

Use getSession when you need only SessionState. For example, in an App Router Server Component using the exports from createAppRouterAuth:

import { getSession } from "@/lib/auth/server";

export default async function SessionStatus() {
  const session = await getSession();

  return <p>{session.isAuthenticated ? "Signed in" : "Signed out"}</p>;
}

When you need an auth context rather than just session state, choose the getAuth method that matches your operation:

Method	When to use	Result
getAuth.viewer	Authentication is optional	Auth context with session: null when no user is authenticated
getAuth.user	An operation requires a user	User auth context, or null when no valid user session is available
getAuth.org	Organization access	Organization auth context, not a user session

Resolve auth before you create a GraphQL client. Authentication can send a token refresh request. The client then submits each GraphQL operation once and applies the selected error policy to that response.

Session lifecycle

Verify the token

Blueprint Auth checks the token signature, expiry, user ID, intended use, authentication method, and issuer. An issuer identifies the system that created the token. Blueprint Auth gets public verification keys from a JSON Web Key Set (JWKS), then creates the session from the verified token.

Blueprint Auth selects one token source for each request and verifies its token. It does not use the next source if verification fails. A cookie or request header does not authenticate a user by itself.

OAuth login verifies both the identity token and the access token. Both tokens must identify the same user.

Refresh the session

Blueprint Auth refreshes eligible user access tokens before they expire. The default threshold is 60 seconds. A web session is eligible when an email or OAuth access token has its matching refresh token. A mobile web view session is eligible when it uses email authentication and has MWRefreshToken.

Blueprint Auth also refreshes when an access token is missing or expired. It verifies each replacement access token before use. Refresh tokens are used only to obtain replacement access tokens.

If Kraken rejects an expired, invalid, or unauthorized refresh token, Blueprint Auth ends the local session. If Kraken is unavailable or rate limits a proactive refresh, Blueprint Auth keeps the current verified access token. During proactive refresh, Blueprint Auth also keeps the current token if the replacement access token fails verification or does not match the session.

If a persistence failure prevents Blueprint Auth from writing the access token cookie, it still uses the verified replacement for the current request. Configuration and programming errors during the refresh exchange, replacement verification, or cookie write propagate in all refresh modes. If no valid access token remains, an unavailable refresh service returns TokenRefreshUnavailable. Other unexpected refresh failures propagate.

End or replace the session

Logout removes the local session cookies. For OAuth sessions, Blueprint Auth also asks Kraken to revoke the token and end the upstream session. Local logout completes after an upstream failure.

A masquerade login replaces the current session. A scoped login keeps an existing session that is not scoped when both sessions identify the same user. Otherwise, the scoped login replaces the current session. Blueprint Auth verifies the new token before it changes the session.

Configure session verification

Configure the exact access token issuers and the Kraken authentication endpoint. If you use organization auth, configure a server cache adapter for organization tokens.

Follow the setup guide for your router:

• Pages Router setup
• App Router setup

For specific flows, read these guides:

• Kraken OAuth
• Anonymous authentication
• Masquerade authentication
• Organization authentication

Use the API reference for configuration fields, handler responses, cookies, and error codes.

FAQ

What is a session?

A Blueprint session describes the authenticated user for the current request. Blueprint does not store user data in a server session. It creates session state only after verifying a signed JSON Web Token (JWT) from the request.

SessionState contains these fields, but no access or refresh tokens:

Field	Description	Type
authMethod	How the user authenticated	"email" | "oauth" | "scoped" | "masquerade" | null
authSource	Where Blueprint Auth found the token	"web" | "mobile-web-view" | "override" | null
isAuthenticated	Whether Blueprint Auth verified a user token	boolean
sub	The verified user ID	string | null

An unauthenticated session has isAuthenticated: false; its other identity fields are null.

An AuthContext is different from SessionState: it can contain access tokens and request headers. Keep auth contexts on the server and out of Client Components, browser props, logs, and public output.

What is a session used for?

Use isAuthenticated to choose between signed-in and signed-out content. Use authMethod when content depends on the sign-in method. Use authSource when content depends on the web, mobile web view, or request override source.

How are sessions synchronized?

Blueprint uses React Query to keep the client view of the session current. The useSession hook can refetch after a component mounts, the window receives focus, or the network reconnects. These checks update the session in open browser tabs.

Refetching session state is distinct from refreshing an access token. Token verification and refresh happen during server-side auth resolution, as described in the session lifecycle.