updateSession

Complete API reference for the api.updateSession method, allowing programmatic modification of active session claims and stateless token payloads.

The api.updateSession method modifies or refreshes the data stored in the current user's session payload without requiring them to sign out and back in.

syntax.ts

import { api } from "@/lib/auth"

const session = await api.updateSession({
  headers: getHeaders(),
  session: {
    user: {
      nickname: "newnickname",
    },
  },
})

Reference

Parameters

Parameter	Type	Required	Description
options	`UpdateSessionAPIOptions`	Yes	An object containing the session updates and request context.

UpdateSessionAPIOptions

Option	Type	Default	Description
session	`DeepPartial<Session<DefaultUser>>`	undefined	The partial session data to merge into the current session.
request	`Request`	undefined	The request object from the server-side context.
headers	`Headers`	undefined	The headers object from the server-side context.
redirect	`boolean`	`true`	Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`).
redirectTo	`string`	undefined	The URL to redirect to after a successful update.
~~skipCSRFCheck~~	`boolean`	`false`	~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release.
doubleSubmitToken	`string`	undefined	Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.

At least one of request or headers is required to construct the incoming URL and validate redirect URLs.

Returns

Return Type	Description
`Promise<UpdateSessionAPIReturn<DefaultUser>>`	Resolves to an object containing the updated session data, `redirect`, and `success`.

Behavior

The session token's integrity is verified before applying the update. If the session is invalid or expired, the call resolves with success: false rather than throwing.
The doubleSubmitToken option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.

This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.

Providing doubleSubmitToken does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie validation on top of the standard CSRF checks already performed by Aura Auth.
The return value depends on the redirect option:
- redirect: true (default) — redirects to redirectTo (or the default post-update URL) via the Location header.
- redirect: false — resolves to an object with the updated session, redirect: false, and success, letting you handle navigation yourself.
If the update fails (invalid session, or data that doesn't match identity.schema), success is false.

Usage

Update session data

update-session.ts

import { api } from "@/lib/auth"

const session = await api.updateSession({
  session: {
    user: {
      nickname: "newnickname",
    },
  },
  headers: getHeaders(),
})

manual-navigation.ts

import { api } from "@/lib/auth"

const output = await api.updateSession({
  session: {
    user: {
      nickname: "newnickname",
    },
  },
  headers: getHeaders(),
  redirectTo: "/dashboard",
})

double-submit.ts

import { api } from "@/lib/auth"

const output = await api.updateSession({
  session: {
    user: {
      nickname: "newnickname",
    },
  },
  headers: getHeaders(),
  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
})