Class AnonymousSessionClient

Creates a new anonymous session.

Calls POST /anonymous/token without a session token to establish a fresh anonymous identity. Returns a session containing both the session token (for future renewal) and an access token (for calling APIs).

Optionally accepts up to 1 KB of metadata that is attached to the anonymous identity at creation time. Metadata is set once and cannot be changed after the session is created.

Browser caveat — metadata and existing sessions. This method sends credentials: 'include', so the auth0_anon cookie is sent automatically in a browser. If that cookie is already set when metadata is supplied, Auth0 treats the request as a renewal (not a fresh create) and rejects metadata with invalid_request: metadata cannot be provided when session_token is present. This happens because the cookie overrides the body on the server side — the caller never sees the cookie and has no way to clear it. To recover, catch the invalid_request error and call getAccessToken() without metadata to renew the existing session instead.

Throws

When the request fails

Example

const session = await authClient.anonymous.createSession({
  audience: 'https://api.example.com',
  metadata: { source: 'landing-page' },
});
Copy

Returns a valid anonymous session, creating or renewing it as needed.

This is the primary entry point for obtaining an anonymous access token. The calling SDK (auth0-spa-js, auth0-server-js) is responsible for checking token expiry and deciding when to call this method.

Behaviour:

1. No sessionToken — creates a fresh anonymous session.
2. sessionToken provided — re-mints the access token for the existing session.
3. If the session token has expired (session_expired or invalid_session_token) — silently creates a fresh anonymous session instead. Any metadata previously attached to the session is permanently lost. The returned session will have sessionReplaced: true to signal that a new identity was minted — the previous sub and any associated state are gone.
4. For all other errors — throws an AnonymousSessionError.

Throws

For non-recoverable errors

Example

// First visit — no session yet
const session = await authClient.anonymous.getAccessToken({
  audience: 'https://api.example.com',
});

// Subsequent visit — renew existing session token
const renewed = await authClient.anonymous.getAccessToken({
  sessionToken: storedSessionToken,
  audience: 'https://api.example.com',
});
Copy

Ends an anonymous session.

Calls POST /anonymous/logout. Auth0 identifies the session via the auth0_anon cookie (sent automatically through credentials: 'include') and clears it in the response. If the cookie is not cleared, it is sent to /authorize on the next login, re-attaching the anonymous identity to the authenticated user.

When called server-side (e.g. via auth0-server-js), the user's browser cookie is not forwarded to Auth0 and the Set-Cookie clear response does not reach the browser — the higher-level SDK must handle cookie proxying.

Issued access tokens are not revoked and remain valid until natural expiry.

Throws

When the request fails

Example

await authClient.anonymous.logout();
Copy

Mints a short-lived session transfer ticket for linking an anonymous session during an interactive login flow.

Calls POST /anonymous/token with audience: "urn:auth0:anon_transfer" and returns the resulting anon_transfer_token — a single-use JWE valid for 30 seconds. The upper-layer SDK (auth0-spa-js, auth0-server-js) appends it to the /authorize URL so the platform can associate the anonymous identity with the authenticated user.

Returns null on any failure so callers can proceed with login unblocked.

Example

const token = await authClient.anonymous.mintTransferToken(session.sessionToken);
if (token) {
  authorizationParams.anon_transfer_token = token;
}
Copy