The problem with a single, long-lived refresh token

The simplest possible refresh flow looks like this: issue a refresh token at login, store it, and let the client trade it for a new access token whenever the old one expires. The refresh token itself never changes.

This works, until the token leaks. Browser history, a logging system that captures request bodies, a compromised device, a misconfigured CDN cache — any of these can expose a long-lived refresh token, and once it's out, it's valid until it naturally expires (which, for a refresh token, is often weeks or months). There's no signal that anything went wrong, and no way to distinguish the attacker's usage from the legitimate user's.

Rotation: the first real improvement

The standard fix is rotation: every time a refresh token is used, it's invalidated and a brand new one is issued in its place. The client must always use the newest token; using an old one is now, by definition, invalid.

This alone is a real improvement, but it has a gap that's easy to miss: rotation without any memory of what happened doesn't detect theft, it just delays the consequences of it. If an attacker steals a refresh token and uses it once, they get a valid new token — same as anyone else who presents a valid token. There's nothing in a bare rotation scheme that distinguishes "the legitimate user refreshed" from "an attacker who stole the token refreshed."

Reuse detection: the piece that's usually missing

Here's the insight that makes rotation actually secure: once a refresh token has been used and rotated away, it should never be valid again — not even once. If it's ever presented a second time, that's not a normal client mistake, it's a signal. It means someone has a copy of a token that the legitimate holder already moved past — which can only happen if that token leaked at some point.

When this happens, the correct response isn't "reject this one token." It's "revoke every token descended from the same original login." Here's why that specific scope matters.

Imagine a normal login produces token A. The client rotates: A → B. Now imagine an attacker had also gotten a copy of A (say, from a logged request) and tries to use it after the legitimate client already rotated to B. The attacker's request with A fails — good, A is already dead — but if you stop there, B (which the legitimate client is now actively using) is untouched. The attacker doesn't get in, but there's no signal that anything happened, and if the attacker actually got a copy of a token before the legitimate client rotated it, whoever wins the race gets B, and the other party's next refresh attempt is the one that reveals reuse — at which point you need to kill the whole chain, because you can no longer be sure which of the two parties holding pieces of that chain is legitimate.

The rule that makes this tractable: track a family, not just individual tokens. Every token descended from one original login shares a family_id. Reuse of any token in that family — detected the moment an already-revoked token is presented again — kills every token sharing that family ID, including ones that were legitimately rotated forward. Both the attacker and the legitimate user get logged out. That's an intentional, correct outcome: the alternative is guessing which party is legitimate, and guessing wrong is worse than forcing a full re-login.

What this looks like in a real schema

CrydenSync's sessions table carries both an id (unique per token) and a family_id (shared across a rotation chain):

CREATE TABLE sessions (
    id          UUID PRIMARY KEY,
    family_id   UUID NOT NULL,
    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_hash  TEXT NOT NULL UNIQUE,
    ip          TEXT,
    user_agent  TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    revoked_at  TIMESTAMPTZ
);

CREATE INDEX idx_sessions_family_id ON sessions(family_id);

Two things worth noting immediately:

token_hash, not the raw token. The refresh token itself is never stored. On issue, the raw token (32 bytes from crypto/rand, hex-encoded) is hashed with SHA-256 before it touches the database. If the database is ever compromised, there's nothing usable inside it — an attacker with read access to the table still can't reconstruct a valid token from a hash.

revoked_at, nullable, is the whole state machine. A session with revoked_at IS NULL is live. Anything else is dead. Reuse detection is just: "was this token already revoked when it was presented?"

The rotation logic itself

func Rotate(
    ctx context.Context,
    sessions store.SessionStore,
    gen TokenGenerator,
    ids security.IDGenerator,
    rawToken string,
) (RefreshResult, error) {
    hash := HashToken(rawToken)

    existing, err := sessions.GetByTokenHash(ctx, hash)
    if err != nil {
        return RefreshResult{}, ErrInvalidToken
    }

    if existing.RevokedAt != nil {
        // Reuse of a token that was already rotated away — the
        // whole family is compromised, not just this token.
        if revokeErr := sessions.RevokeFamily(ctx, existing.FamilyID); revokeErr != nil {
            return RefreshResult{Session: existing}, revokeErr
        }
        return RefreshResult{Session: existing}, ErrTokenReused
    }

    newRaw, err := gen.New()
    if err != nil {
        return RefreshResult{}, err
    }
    newID, err := ids.New()
    if err != nil {
        return RefreshResult{}, err
    }

    newSession := store.Session{
        ID:        newID,
        FamilyID:  existing.FamilyID, // stays constant across the whole chain
        UserID:    existing.UserID,
        TokenHash: HashToken(newRaw),
        IP:        existing.IP,
        UserAgent: existing.UserAgent,
    }

    if err := sessions.RotateToken(ctx, existing.ID, newSession); err != nil {
        return RefreshResult{}, err
    }

    return RefreshResult{RawToken: newRaw, Session: newSession}, nil
}

Two subtleties in this function are easy to get wrong, and both were real bugs caught during development, not hypothetical concerns.

Subtlety 1: the reuse-detected error path still needs to carry context

Notice that on the ErrTokenReused path, the function returns RefreshResult{Session: existing} — not a zero-valued RefreshResult{}. This matters because the caller needs existing.UserID and existing.FamilyID to write an accurate audit log entry (token_reuse_detected, attributed to the right user). The first version of this function returned a zero value on that path, which meant the resulting security event had no user attached to it — completely undermining the point of logging it in the first place. If you're building this yourself: whatever error path represents your most security-critical event is exactly the path where losing context is least acceptable, and it's an easy place for that kind of gap to hide.

Subtlety 2: rotation must be atomic, or you've built a worse bug than the one you're fixing

Look at the last real step: sessions.RotateToken(ctx, existing.ID, newSession). This is not two separate calls (revoke the old, then create the new). It's one atomic operation, and here's the Postgres implementation underneath it:

func (s *SessionStore) RotateToken(ctx context.Context, oldSessionID string, newSession store.Session) error {
    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback() // no-op if Commit succeeds

    result, err := tx.ExecContext(ctx, `
        UPDATE sessions SET revoked_at = now()
        WHERE id = $1 AND revoked_at IS NULL
    `, oldSessionID)
    if err != nil {
        return err
    }
    if err := checkRowsAffected(result); err != nil {
        return err
    }

    _, err = tx.ExecContext(ctx, `
        INSERT INTO sessions (id, family_id, user_id, token_hash, ip, user_agent)
        VALUES ($1, $2, $3, $4, $5, $6)
    `, newSession.ID, newSession.FamilyID, newSession.UserID,
       newSession.TokenHash, newSession.IP, newSession.UserAgent)
    if err != nil {
        return err
    }

    return tx.Commit()
}

If revoking the old token and creating the new one were two independent database calls, a crash between them leaves a session family with no live token in it at all — not a security hole exactly (the user just gets logged out), but a real reliability bug, and one that would be maddening to reproduce and debug in production. Wrapping both operations in a single transaction, with defer tx.Rollback() as a safety net, means the operation either fully succeeds or leaves no trace of having started. This is the kind of thing that's invisible in a demo and very visible the first time it happens under real concurrent load.

Proving it actually works

None of the above matters if it isn't tested against real conditions. Here's the property that actually matters, verified with a real integration test against live Postgres (not mocked):

func TestRotate_ReuseDetectionRevokesEntireFamily(t *testing.T) {
    // ... set up an original session, rotate it once (A -> B) ...

    // Replay the ORIGINAL token, which is now stale.
    _, err := Rotate(ctx, sessions, gen, ids, rawOriginal)
    if err != ErrTokenReused {
        t.Fatalf("expected ErrTokenReused, got %v", err)
    }

    // The critical assertion: token B — the one that legitimately
    // rotated forward and was never "stolen" — must ALSO be dead now.
    _, err = Rotate(ctx, sessions, gen, ids, firstResult.RawToken)
    if err == nil {
        t.Error("expected the legitimately rotated token to also be revoked")
    }
}

And, one level up, the same property proven over real HTTP, against a running server, hitting real endpoints:

OK   refresh rotation
OK   reused (old) refresh token rejected — the property that matters most
OK   session family fully revoked — even the legitimately rotated token now dead

That second layer of proof matters more than it might seem. Unit tests prove the Go function behaves correctly in isolation. An end-to-end test against a real, running HTTP server proves the whole system — the handler, the JSON serialization, the actual database round trip — produces the right outcome for a real client. Both layers caught different classes of bugs during development; neither alone would have been sufficient.

What a client should actually do with this

If you're consuming an API built this way (this exact contract is what CrydenSync's HTTP API exposes), the client-side handling is simple but easy to get subtly wrong:

async function refreshTokens(refreshToken) {
  const res = await fetch("/v1/refresh", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh_token: refreshToken }),
  });

  if (res.status === 401) {
    const { error } = await res.json();
    if (error.code === "token_reused") {
      // The entire session family is dead. There is no other stored
      // token that will work. Clear everything and force login.
      clearStoredTokens();
      redirectToLogin();
      return;
    }
  }

  const { data } = await res.json();
  storeTokens(data); // overwrite BOTH tokens — never keep the old one around
}

The mistake to avoid: treating token_reused like any other refresh failure and retrying, or worse, falling back to some other cached token. There isn't one. Once you're in this state, a full re-login is the only correct next step.

The takeaway

"Refresh token rotation" as a phrase undersells what actually needs to happen. Rotation alone slows down misuse of a leaked token; it doesn't detect it. The piece that makes the whole scheme actually secure — tracking a family, detecting reuse of an already-rotated token, and revoking the entire chain the instant that happens — is exactly the part most quick tutorials skip, because it requires real state (a family_id, a revocation timestamp), a genuinely atomic database operation, and tests that go looking for the failure mode instead of just the happy path.

If you want to see the whole thing in context the store interfaces, the Postgres schema, the full test suite — the code is open source: github.com/crydensync/cryden.

CrydenSync is a self-hosted, framework-agnostic authentication engine for Go. No hosted service, no telemetry, no vendor lock-in your users stay in your own database. If this kind of design work interests you, we're looking for testers and documentation contributors.