What is a refresh token, and why does it exist?

Access tokens are deliberately short-lived — often valid for just a few minutes — to limit how long a stolen one remains useful. But asking a user to fully log in again every few minutes would be unbearable. The refresh token solves this: it’s a longer-lived credential that lets an application quietly obtain a brand-new access token, behind the scenes, without bothering the user at all. As long as the refresh token remains valid, the user’s session effectively continues seamlessly, even though each individual access token expires quickly.

What does “rotation” actually mean here?

Without rotation, a single refresh token can be used over and over again, for as long as it remains valid — sometimes for hours, days, or even longer, depending on configuration. Refresh Token Rotation changes this: every time the refresh token is used, Keycloak issues both a new access token and a brand-new refresh token, and immediately invalidates the one that was just used. The refresh token, in other words, is single-use — spend it once, and a fresh replacement takes its place.

Why does rotation matter for security?

If a refresh token is somehow copied — through a compromised device, a logging mistake, or intercepted network traffic — and rotation is not in place, that stolen copy remains just as valid as the legitimate one, for as long as it hasn’t expired. With rotation enabled, the moment either the legitimate client or the attacker uses the token, a new one is issued and the old one is dead. This doesn’t just limit a stolen token’s usefulness — it creates a detectable signal: if the token that was already used and invalidated is presented again, Keycloak knows something is wrong.

Key vocabulary, explained simply

graph TB
    C[Client] -->|presents refresh token| TE[Keycloak Token Endpoint]
    TE --> CHK{Is this the current
valid refresh token
for the session?}
    CHK -->|yes| ISSUE[Issues new access token
+ new refresh token]
    ISSUE --> SS[Updates Session Store
with new valid token reference]
    ISSUE --> INV[Invalidates old refresh token]
    CHK -->|no - already used| REUSE[Reuse Detected]
    REUSE --> REVOKE[Revokes entire session
as a precaution]
    

Component breakdown

Where this is configured in the admin console

Inside the Keycloak Admin Console, refresh token behavior, including rotation-related settings, is typically found under Realm Settings → Tokens, or in specific client advanced settings for per-client overrides. Administrators can control whether refresh tokens are reused or rotated, and tune related session and token lifetime settings that interact with rotation behavior.

Why is this handled at the session level, not just the token level?

Tracking “which specific refresh token is currently valid” has to be tied to the broader session record, not just evaluated in isolation per token, because rotation is fundamentally about maintaining a single, continuously advancing chain of trust for one login. The session is the anchor; the rotating refresh tokens are simply the current “state” of that anchor at any given moment, updated with each legitimate use.

The normal refresh path

When a client sends a valid, currently-live refresh token to Keycloak’s token endpoint, Keycloak checks that this token matches the one it has on record as the current valid token for that session. If it matches, Keycloak generates a new access token and a new refresh token, updates the session record to mark this new refresh token as the current valid one, and returns both to the client. The refresh token that was just presented is now considered spent — any future attempt to use it again will not match the session’s updated record.

The reuse-detection path

If a refresh token is presented that Keycloak recognizes as having already been used and replaced — meaning it no longer matches the session’s current valid token — this is treated as a red flag. The most likely explanations are either a legitimate but delayed retry (handled gracefully within a short grace period) or, more seriously, an attacker attempting to use a stolen, already-superseded token. Because Keycloak generally cannot distinguish these two cases with certainty, its typical response is to revoke the entire session as a precaution, forcing both the legitimate user and any potential attacker to re-authenticate from scratch.

Why the grace period exists

In real-world network conditions, a client might occasionally send two refresh requests in quick succession — due to a retry after a slow or dropped response, for example — even though only one was truly intended. Without any tolerance, this could cause Keycloak to treat a harmless double-request as an attack and needlessly revoke a legitimate session. A short grace period allows a very recently superseded refresh token to still be accepted briefly, reducing false positives while still closing the door on any meaningfully delayed reuse attempt.

Step-by-step: a single refresh cycle with rotation enabled

sequenceDiagram
    participant Client as Legitimate Client
    participant Keycloak
    participant Attacker

    Client->>Keycloak: Refresh Token A
    Keycloak-->>Client: New Access Token + Refresh Token B
    Note over Attacker: Somehow obtains a copy
of Refresh Token A
    Attacker->>Keycloak: Refresh Token A (already used)
    Keycloak->>Keycloak: Detects reuse of superseded token
    Keycloak-->>Attacker: Rejected
    Keycloak->>Keycloak: Revokes entire session as precaution
    Client->>Keycloak: Refresh Token B (now also invalid)
    Keycloak-->>Client: Rejected - must log in again
    

Notice the outcome in that diagram: both the attacker and the legitimate client end up needing to log in again once reuse is detected. This is an intentional, if slightly inconvenient, trade-off — Keycloak cannot reliably tell which party is the legitimate one once an already-superseded token has been replayed, so the safest response is to end the session for everyone and force a fresh, verified login.

The lifecycle of a rotating refresh-token chain

Why rotation matters especially for public clients

Public clients — typically single-page applications and mobile apps — cannot hold a client secret securely, since anything embedded in browser-accessible code or a distributed app binary can, in principle, be extracted. This makes their refresh tokens comparatively more exposed to theft through cross-site scripting, malicious browser extensions, or a compromised device, compared to a confidential backend client that can better protect its credentials. Rotation specifically compensates for this weaker baseline protection by ensuring even an exposed refresh token has a very short useful lifespan.

What reuse detection should trigger, beyond just rejection

Simply rejecting a reused, superseded refresh token is the minimum response; a more security-conscious deployment also treats detected reuse as a genuine incident signal worth investigating — potentially notifying the user of the forced session termination, logging the event prominently for security review, and in some cases prompting additional verification on the next login, rather than silently forcing a quiet re-login with no further follow-up.

Rotation complements, but doesn’t replace, other token protections

Rotation specifically limits the window of usefulness for a stolen refresh token; it doesn’t prevent theft in the first place, nor does it address access token theft directly. Combining rotation with secure storage practices, short access token lifetimes, and mechanisms like DPoP for especially sensitive clients provides a more complete defense than relying on rotation alone.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes