Refresh and Logout

Token and session lifetimes

Keycloak manages three related concepts that control how long a user stays logged in:

Concept	Typical default	What it controls
Access token lifespan	5 minutes	How long the JWT is valid before the backend rejects it
Refresh token lifespan	30 minutes (SSO Session Idle)	How long a refresh token can be used to get new access tokens
SSO session max	10 hours	Absolute maximum session length, even with active refresh

When the access token expires, the frontend should use the refresh token to silently get a new one — without forcing the user to log in again. When the SSO session expires, the user must re-authenticate.

Refreshing tokens with updateToken

keycloak.updateToken(minValidity) is the idiomatic way to handle refresh in keycloak-js. Call it before any API request; if the current access token will expire within minValidity seconds, keycloak-js silently exchanges the refresh token for a new access token:

// Refresh the token if it expires within 60 seconds,
// then call the API with the fresh token.
async function callApi(path) {
  try {
    await keycloak.updateToken(60);
  } catch {
    // Refresh token has expired — force re-login.
    keycloak.login();
    return;
  }

  const response = await fetch(`https://api.example.com${path}`, {
    headers: { Authorization: `Bearer ${keycloak.token}` },
  });
  return response.json();
}

Copy refresh snippet ⧉

If updateToken rejects (the refresh token is expired or revoked), the user’s session is gone and you should redirect them to login with keycloak.login().

Logging out properly

Calling a local “clear state” function in your app is not enough. The user’s SSO session still exists in Keycloak, which means they could immediately access other apps in the same realm without re-authenticating — or even return to your app and bypass the login screen.

A proper logout hits Keycloak’s end-session endpoint. keycloak-js does this for you:

// Redirect to Keycloak's end-session endpoint,
// then back to your app's home page.
keycloak.logout({ redirectUri: 'https://app.example.com/' });

Copy logout snippet ⧉

Under the hood this redirects the browser to:

/realms/{realm}/protocol/openid-connect/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https://app.example.com/

Keycloak clears the SSO session cookie, marks the refresh token as revoked, and redirects back to your app.

What gets cleared

Action	Clears local token	Clears Keycloak session
Local state reset only	Yes	No
keycloak.logout()	Yes	Yes

🔐 Hit the end-session endpoint — local logout is not enough

Clearing your app’s local state only removes tokens from memory. The Keycloak SSO session cookie in the browser remains valid. Until you call keycloak.logout(), the user is still globally logged in and can re-enter your app (or any other app in the realm) without a password prompt.

What does keycloak.updateToken(60) do?

It sets the access token lifespan to 60 seconds It forces the user to re-authenticate if idle for 60 seconds It silently refreshes the access token if it expires within 60 seconds It logs out the user after 60 seconds

What should your app do when keycloak.updateToken() rejects (throws)?

Retry the refresh up to three times Silently swallow the error and proceed with the expired token Call keycloak.login() to redirect the user back to Keycloak for re-authentication Store the last valid token in localStorage and use it

Why is clearing local app state alone insufficient for logout?

Because keycloak-js cannot clear its internal token cache Because the Keycloak SSO session cookie in the browser remains valid until the end-session endpoint is called Because the backend still holds the access token Because the refresh token is stored in localStorage by default

What does the SSO Session Idle timeout control?

How long the access token JWT is valid How long the Keycloak admin console session lasts How long a refresh token can be used to obtain new access tokens without user interaction How long until Keycloak restarts

Submit

Mark as complete