What does “reuse” actually mean?

When refresh token rotation is enabled, every time a refresh token is successfully used to obtain a new access token, Keycloak also issues a brand-new refresh token and marks the one just used as superseded — no longer the current, valid token for that session. Reuse is simply the event of someone presenting that superseded token again, after it’s already been replaced. Under normal, correct client behavior, this should never happen — a well-behaved application always uses the newest token it was given, never an older one that’s already been swapped out.

Why does reuse happening at all matter so much?

If reuse only ever happened by innocent accident, it wouldn’t be worth building dedicated detection around. But there’s a specific, realistic scenario where it happens for a genuinely serious reason: an attacker has stolen a copy of a refresh token. If both the legitimate client and the attacker now hold a copy of the same token, whichever one uses it first triggers rotation and gets the new one — and the other party, still holding the now-superseded original, will trigger reuse detection the moment they try to use it. Reuse detection turns this specific, otherwise invisible race into a loud, unmistakable signal.

Why is detecting reuse different from just preventing it?

Rotation itself already prevents an old token from working again — that part is simple rejection. Reuse detection goes a step further: it specifically recognizes this particular kind of rejection as meaningfully different from an ordinary expired or invalid token, and treats it as a signal worth acting on, typically by protectively shutting down the entire underlying session rather than just declining that one request.

Key vocabulary, explained simply

graph TB
    SS[Session Store] --> CUR["Current Valid
Refresh Token Reference"]
    TE[Token Endpoint] -->|presented token| CMP{Matches current
valid reference?}
    CMP -->|yes| ROT[Rotate: issue new token,
update reference]
    CMP -->|no, but within grace period| GRACE[Accept under
grace tolerance]
    CMP -->|no, outside grace period| DETECT[Reuse Detected]
    DETECT --> RESP[Protective Response:
revoke session, log event]
    

Component breakdown

Where this is configured in the admin console

Reuse detection isn’t a separate toggle from rotation itself — it’s an automatic behavior of Keycloak’s token endpoint once rotation is enabled. The relevant tunable setting administrators actually configure is the grace period, typically found alongside other token and session settings under a realm or client’s advanced configuration, controlling how strictly or leniently near-simultaneous refresh attempts are treated.

Why is a single “current valid token” reference enough to make this work?

Because Keycloak only ever considers one refresh token, per session, as currently valid at any moment, any other token presented against that session is automatically distinguishable as either the legitimate next-in-line replacement or something that’s already been superseded. This simple, single-pointer design is what makes reuse detection reliable without requiring Keycloak to maintain a complex history of every token ever issued — it only needs to know what’s current right now.

The three possible outcomes of a refresh attempt

When a refresh token arrives at Keycloak’s token endpoint, exactly one of three things happens. First, if the token matches the session’s current valid reference, rotation proceeds normally — a new access and refresh token are issued, and the reference is updated. Second, if the token doesn’t match but falls within the configured grace period (meaning it was only very recently superseded), it may still be accepted, treated as a harmless, delayed duplicate of a legitimate request. Third, if the token doesn’t match and falls outside the grace period, this is treated as genuine reuse — a clear, high-confidence signal that something is wrong.

Why the grace period exists as a middle ground

Real network conditions occasionally cause a client to send what looks like two refresh requests very close together — for example, a slow response triggers an automatic retry, even though the original request actually succeeded moments earlier. Without any tolerance at all, this ordinary, harmless situation would trigger the same severe response as genuine theft. The grace period exists specifically to absorb this narrow category of legitimate near-simultaneous requests, without meaningfully weakening protection against a genuinely delayed, malicious reuse attempt.

What happens the instant reuse is detected

Once Keycloak determines a presented token is genuinely reused — outside any grace tolerance — its typical, protective response is to revoke the entire underlying session, not just reject that one request. This is a deliberate, conservative choice: because Keycloak cannot reliably tell, from the reuse event alone, whether the party presenting the old token is the legitimate user or an attacker, ending the whole session forces everyone involved to re-authenticate from scratch, cutting off whatever access an attacker might otherwise have continued to hold through their own copy of a still-live session.

Step-by-step: what happens from a stolen token to a triggered alarm

sequenceDiagram
    participant Legit as Legitimate Client
    participant KC as Keycloak
    participant Attacker

    Note over Attacker: Has stolen a copy of
Refresh Token A
    Legit->>KC: Uses Refresh Token A first
    KC-->>Legit: Issues Refresh Token B (A now superseded)
    Attacker->>KC: Attempts to use Refresh Token A
    KC->>KC: Detects reuse - A no longer current
    KC-->>Attacker: Rejected
    KC->>KC: Revokes entire session as precaution
    Legit->>KC: Later tries to use Refresh Token B
    KC-->>Legit: Rejected - session already revoked, must re-login
    

Notice the outcome for the legitimate client in that diagram — they did everything right, used the newest token they had, and still end up needing to log in again. This is the direct cost of the protective response’s inherent uncertainty: Keycloak cannot tell, from the reuse event alone, which of the two parties holding copies of the token was the legitimate one, so it treats both equally and ends the session for everyone, prioritizing closing off the attacker’s access over sparing the legitimate user a minor inconvenience.

The lifecycle of a detection event, from trigger to resolution

Treating detection events as genuine incidents, not routine noise

The single most important security practice around reuse detection is simply making sure the events it generates are actually seen by someone, or something, capable of acting on them. A detection event sitting unread in a log file provides essentially none of the protective value it’s capable of offering — the real security benefit comes specifically from timely awareness and response.

Correlating reuse events with other signals

A single reuse-detection event is a strong but not conclusive signal on its own. Correlating it with other available context — the IP address or location associated with each side of the reuse attempt, whether it coincides with other suspicious activity on the same account, or whether similar events are happening across multiple unrelated accounts at once — helps distinguish an isolated, likely-benign edge case from a genuine, active attack pattern worth immediate escalation.

What reuse detection does not protect against

It’s worth being precise about the limits here: reuse detection only fires when a superseded token is presented again — it says nothing about a scenario where an attacker steals a token and simply uses it once, successfully, before the legitimate client ever gets a chance to. In that specific case, from Keycloak’s perspective, the attacker’s use looks like an entirely normal, successful rotation, with no reuse ever technically occurring. This is why reuse detection is one layer of defense, not a complete solution to token theft on its own.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes