Before diving into Keycloak specifics, let’s build a plain-English mental model of the problem an offline token solves.

Keycloak is an open-source Identity and Access Management (IAM) server. It handles logging users in, issuing proof of who they are, and issuing proof of what they’re allowed to do. Every time a user logs in, Keycloak hands out a small bundle of tokens: an access token (a short-lived pass that says “this request is allowed”), an ID token (a statement of who the user is), and a refresh token (a way to get new access tokens without asking the user to log in again).

Normally, a refresh token is tied to the user’s login session. The moment that session ends — because the browser closed, the SSO session timed out, or the user simply stopped being active — the refresh token stops working too. That’s perfectly fine for a web app that only needs to act while the user is sitting in front of the screen. But plenty of real applications need to keep doing work after the user has left: a nightly batch job that syncs a user’s calendar, a background service that processes an uploaded video, or a mobile app that wants to silently refresh data overnight.

An offline token is Keycloak’s answer to exactly that need. It is a special kind of refresh token that is intentionally decoupled from the browser session. Once issued, it keeps working — even after the user logs out of their browser, closes their laptop, or the normal session expires — until one of three things happens: the token is explicitly revoked, it becomes idle for too long, or an administrator deletes it.

To see why the offline token is special, it helps to line it up next to the other tokens Keycloak issues.

Keycloak follows the OAuth 2.0 and OpenID Connect standards, which define a small family of tokens. Each one has a distinct job, a distinct lifetime, and a distinct level of trust attached to it.

Notice that an offline token is not a fourth, entirely separate token type from a protocol point of view — technically it is a refresh token. What makes it “offline” is the scope used to request it and the special lifecycle rules Keycloak applies once that scope is present.

Nothing about offline tokens happens by accident — a client has to explicitly ask for one.

Keycloak ships with a built-in OAuth scope called offline_access. This scope exists specifically so that a client application can say, in its authorization request, “please give me a refresh token that keeps working even after this session ends.” When a login request includes this scope, Keycloak marks the resulting refresh token as an offline token internally and treats it under a different set of rules from that point forward.

Behind that scope sits a realm-level client scope also named offline_access, and behind that sits a composite realm role of the same name. For a user to be granted an offline token, three conditions generally need to line up: the client must be allowed to request the offline_access scope, the user must be permitted to have that role (directly, through a group, or through a default role mapping), and the authorization request itself must include scope=offline_access alongside the usual openid scope.

Under the hood, Keycloak treats an offline token less like a self-contained secret and more like a claim ticket.

A Keycloak refresh token — offline or not — is a signed JWT (JSON Web Token), but the important part isn’t what’s printed inside it; it’s what Keycloak does when that token is presented back to the server. Keycloak looks up the session the token points to in its own storage. If that session record exists, is still valid, and matches what the token claims, Keycloak issues a fresh access token (and usually a fresh refresh token too, depending on rotation settings).

What makes this “offline” behavior possible is that Keycloak creates a special kind of session for it: an offline user session, separate from the normal, memory-resident SSO session. A regular SSO session lives mostly in a fast in-memory cache (Infinispan) and disappears once the user logs out or the session times out. An offline session, by contrast, is written to Keycloak’s persistent database from the moment it’s created, precisely so it can outlive the transient in-memory session it was born alongside.

flowchart LR
    A["User logs in with
scope=offline_access"] --> B["Keycloak creates a
regular SSO session"]
    B --> C["Keycloak also creates an
Offline User Session"]
    C --> D[("Persisted in the
Keycloak database")]
    B --> E["Access Token issued
(short-lived)"]
    C --> F["Offline (Refresh) Token issued
(long-lived)"]
    F -. "later, user is gone" .-> G["Client presents Offline Token"]
    G --> H["Keycloak looks up
Offline User Session in DB"]
    H --> I["New Access Token issued"]
        

This separation is the whole trick. The regular SSO session can time out, the browser can be closed, cookies can be cleared — none of that touches the offline session record sitting safely in the database. As long as that record exists and hasn’t expired or been revoked, the offline token tied to it keeps working.

Getting an offline token is not a separate endpoint — it’s a small addition to a login flow you likely already know.

Most commonly, offline tokens are obtained through the standard OAuth 2.0 Authorization Code flow, the same flow used for ordinary browser logins. The only change is a single word added to the scope parameter.

It’s worth dwelling on this distinction because it explains almost every quirk of offline token behavior you’ll run into.

One subtlety trips up a lot of newcomers: logging a user out of Keycloak’s normal SSO session does not automatically kill their offline sessions. If you want a “log this user out everywhere, permanently” button, you must explicitly revoke offline tokens too — Keycloak’s admin console and Admin REST API both expose ways to do this, covered later in the Revocation chapter.

Let’s trace a token from birth to eventual death.

sequenceDiagram
    participant U as User
    participant C as Client App
    participant K as Keycloak
    participant DB as Keycloak DB

    U->>C: Logs in, grants offline_access
    C->>K: Authorization Code exchange
    K->>DB: Create Offline User Session
    K-->>C: Access Token + Offline (Refresh) Token
    Note over C: User closes browser and leaves

    C->>K: Later — present Offline Token
    K->>DB: Look up Offline User Session
    DB-->>K: Session found and valid
    K-->>C: New Access Token (+ new Offline Token if rotation enabled)

    Note over K,DB: Weeks pass, still within max lifespan

    C->>K: Present Offline Token again
    K->>DB: Session still valid?
    DB-->>K: Yes
    K-->>C: New Access Token
        

Three settings, all configurable per realm, decide when that session record finally expires:

Where exactly does all of this state live, and what does it mean for running Keycloak at scale?

In a small, single-node Keycloak deployment, this distinction between “in-memory” and “persisted” sessions might feel academic — everything is on one machine anyway. The difference becomes very real in a clustered deployment, which is how most production Keycloak setups run.

Regular SSO sessions live in Infinispan, Keycloak’s embedded distributed cache, replicated across cluster nodes for fast access but not necessarily written to disk. Offline sessions, by contrast, are written straight into Keycloak’s relational database (PostgreSQL, MySQL, MariaDB, and so on, depending on deployment). That single design choice is what lets an offline token survive a full restart of the entire Keycloak cluster — something a purely in-memory session could never do.

“Long-lived” doesn’t mean “never changes” — most deployments rotate the token every time it’s used.

By default, Keycloak issues a new refresh token every time an old one is exchanged for a new access token — this applies to offline tokens too. Practically, that means a well-behaved client shouldn’t treat its offline token as a single, unchanging string to hard-code once. Instead, every time it uses the token, it should store whichever new token comes back in the response, replacing the old one.

Because an offline token can outlive a browser session entirely, Keycloak gives administrators — and users — several deliberate ways to kill one early.

Long-lived credentials are powerful, and power always comes with a bigger blast radius if something goes wrong.

An offline token is, functionally, a standing credential that can act as the user indefinitely. That makes it categorically more sensitive than a short-lived access token. If an attacker steals a valid offline token, they gain a renewable way to impersonate the user until someone notices and revokes it — potentially for weeks or months.

Offline tokens solve a real problem, but they aren’t free of cost.

A few recurring good and bad habits show up again and again in teams adopting offline tokens.

A short, practical checklist for teams about to implement offline tokens for the first time.

Offline tokens show up wherever software needs to act for a user without the user being present.

Because offline tokens represent standing access, operators generally want visibility into how many exist and how they’re being used.

No. An offline token is a special kind of refresh token used to obtain new access tokens later; it is never sent directly to a resource server as proof of authorization the way an access token is.

Yes, unless a realm is specifically configured for indefinite offline access. Idle timeout and maximum lifespan settings both apply, and Keycloak’s cleanup job removes expired sessions automatically.

Yes. Keycloak’s account console lists a user’s granted applications, including offline sessions, and lets the user revoke access directly.

Typically yes — an administrator needs to make the offline_access client scope available to the client, and the user (or a role mapping) must be permitted to hold the offline_access role.

Nothing happens to the token. Because offline sessions are persisted in the database rather than the in-memory cache, they survive restarts, upgrades, and node failures cleanly.

No. It should be reserved for clients that have a genuine, documented need for unattended background access, since each grant creates a long-lived, higher-value credential.

An offline token is Keycloak’s purpose-built mechanism for letting an application act on a user’s behalf long after that user has stepped away — powered under the hood by a persisted, database-backed offline session that lives independently of the ordinary, memory-resident SSO session. It’s requested with a single extra scope, governed by realm-level roles and timeouts, and revocable at any time by the user or an administrator. Used deliberately — narrow in scope, properly secured, and paired with clear revocation paths — offline tokens make genuinely useful background integrations possible without ever forcing the user to sit and wait through repeated logins.