Session & Logout

Overview

The Session API (client.session) provides methods to check authentication state, and the Logout API handles both local and server-side logout scenarios.

Session Management

Checking Authentication State

const isAuthenticated = await client.session.isAuthenticated();

if (isAuthenticated) {
  const user = await client.getUser();
  console.log('Logged in as:', user.name);
} else {
  console.log('Not authenticated');
}

Session Check

Perform a detailed session check that returns structured information:

const result = await client.session.check();

if (result.valid) {
  console.log('Session is valid');
} else {
  console.log('Session invalid:', result.error?.code);
}

SessionCheckResult

Property	Type	Description
`valid`	`boolean`	Whether the session is valid
`error`	`AuthrimError \| undefined`	Error details if the session is invalid

Getting User Information

Retrieve the authenticated user’s profile from the UserInfo endpoint:

const user = await client.getUser();

console.log(user.sub);               // Subject identifier
console.log(user.name);              // Full name
console.log(user.email);             // Email address
console.log(user.email_verified);    // Email verification status
console.log(user.picture);           // Profile picture URL

UserInfo

Property	Type	Description
`sub`	`string`	Subject identifier (unique user ID)
`name`	`string \| undefined`	Full name
`given_name`	`string \| undefined`	First name
`family_name`	`string \| undefined`	Last name
`nickname`	`string \| undefined`	Nickname
`preferred_username`	`string \| undefined`	Preferred username
`profile`	`string \| undefined`	Profile page URL
`picture`	`string \| undefined`	Profile picture URL
`email`	`string \| undefined`	Email address
`email_verified`	`boolean \| undefined`	Whether email is verified
`phone_number`	`string \| undefined`	Phone number
`phone_number_verified`	`boolean \| undefined`	Whether phone is verified
`locale`	`string \| undefined`	Locale
`zoneinfo`	`string \| undefined`	Time zone
`updated_at`	`number \| undefined`	Last update timestamp

Logout

Basic Logout

const result = await client.logout();

if (result.logoutUrl) {
  // Redirect to the authorization server's logout endpoint
  window.location.href = result.logoutUrl;
} else {
  // Local-only logout completed
  console.log('Logged out locally');
}

Logout Options

Parameter	Type	Default	Description
`postLogoutRedirectUri`	`string`	—	URL to redirect after IdP logout
`idTokenHint`	`string`	—	ID token to identify the session
`state`	`string`	—	State parameter for logout callback
`revokeTokens`	`boolean`	`false`	Revoke tokens before logout

Logout with Token Revocation

Revoke tokens at the authorization server before clearing the local session:

const result = await client.logout({
  revokeTokens: true,
  postLogoutRedirectUri: 'https://myapp.com/',
});

if (result.revocation) {
  console.log('Revocation attempted:', result.revocation.attempted);
  console.log('Access token revoked:', result.revocation.accessTokenRevoked);
  console.log('Refresh token revoked:', result.revocation.refreshTokenRevoked);
}

if (result.logoutUrl) {
  window.location.href = result.logoutUrl;
}

Logout with IdP Redirect (RP-Initiated Logout)

Redirect the user to the authorization server’s logout endpoint to end the server-side session:

const result = await client.logout({
  postLogoutRedirectUri: 'https://myapp.com/',
  idTokenHint: await client.token.getIdToken(),
});

if (result.logoutUrl) {
  // Redirect to end the server-side session
  window.location.href = result.logoutUrl;
}

The logoutUrl returned by client.logout() points to the IdP’s end_session_endpoint, which uses GET per the OIDC specification. Never place this URL in an <a> tag. Modern frameworks (Next.js, SvelteKit, Nuxt, etc.) prefetch link targets on hover, which would trigger an unintended logout.

Always trigger logout programmatically from a button click handler:

// ✅ Correct — programmatic redirect from button handler
async function handleLogout() {
  const result = await client.logout({ /* ... */ });
  if (result.logoutUrl) {
    window.location.href = result.logoutUrl;
  }
}

If your application has a /logout route, ensure it is a POST endpoint (e.g., a form action or API route), not a page that can be prefetched via GET.

Local-Only Logout

If you only want to clear the local session without contacting the authorization server:

// Set endpoints.endSession to null in config to disable server logout
const client = await createAuthrimClient({
  // ...
  endpoints: {
    endSession: null,
  },
});

// Or simply don't redirect to the logoutUrl
const result = await client.logout();
// result.localOnly === true

LogoutResult

Property	Type	Description
`logoutUrl`	`string \| undefined`	URL to redirect for server-side logout
`localOnly`	`boolean`	Whether only local cleanup was performed
`revocation`	`object \| undefined`	Token revocation results
`revocation.attempted`	`boolean`	Whether revocation was attempted
`revocation.accessTokenRevoked`	`boolean \| undefined`	Access token revocation result
`revocation.refreshTokenRevoked`	`boolean \| undefined`	Refresh token revocation result
`revocation.error`	`Error \| undefined`	Revocation error (non-fatal)

Front-Channel Logout

The SDK supports Front-Channel Logout, where the authorization server notifies all applications of a logout event via the browser. This is handled automatically when the session ends at the authorization server.

Session change events are emitted when logout is detected:

client.on('session:ended', (event) => {
  console.log('Session ended');
  // Clear UI state, redirect to login, etc.
});

client.on('session:logout_broadcast', (event) => {
  console.log('Logout broadcast received');
  // Another tab or application triggered logout
});

Complete Example

import { createAuthrimClient } from '@authrim/core';

const client = await createAuthrimClient({ /* ... */ });

// Check session on load
async function checkSession() {
  const isAuthenticated = await client.session.isAuthenticated();

  if (isAuthenticated) {
    const user = await client.getUser();
    showUserProfile(user);
  } else {
    showLoginButton();
  }
}

// Logout handler
async function handleLogout() {
  const result = await client.logout({
    revokeTokens: true,
    postLogoutRedirectUri: window.location.origin,
  });

  if (result.logoutUrl) {
    window.location.href = result.logoutUrl;
  } else {
    showLoginButton();
  }
}

// Listen for session changes
client.on('session:ended', () => {
  showLoginButton();
});

Next Steps

Token Management — Token retrieval and refresh
Events — Session and auth event reference
Error Handling — Handle authentication errors