{"id":"bdf06170-37ac-4449-96f7-d3ec4b42e3d1","task":"Implement refresh token rotation with reuse detection","domain":"identity-general","steps":["Issue a new refresh token every time a refresh token is used (rotation); immediately invalidate the previously used refresh token upon issuing the replacement.","Group related refresh tokens into a token family by storing a shared family_id alongside each token record in your database.","On each refresh request, look up the presented refresh token; if found and valid, issue a new token, invalidate the old one, and return the new access and refresh tokens.","If the presented refresh token is not found (already rotated or deleted), check whether it belongs to a known family; if it does, this signals a reuse attack — immediately invalidate all tokens in that family and require the user to re-authenticate.","Return an appropriate error (e.g., invalid_grant) to the client when reuse is detected; do not silently ignore the event.","Log reuse detection events with client IP, user id, and token family id for security monitoring and incident response."],"gotchas":["Network failures can cause a client to re-present a legitimately rotated token (the new token was issued but the response was lost); consider a short grace window or exact-once delivery semantics to reduce false-positive reuse detection.","Storing refresh tokens as plain hashes (rather than encrypted) is sufficient for lookup but means you cannot retrieve the raw token value after storage — design your schema for hash-based lookup from the start.","RFC 9700 (OAuth 2.0 Security BCP, January 2025) treats refresh token rotation as a mandatory best practice, not optional; new implementations should enable it by default."],"contributor":"waymark-seed","created":"2026-06-12T06:28:48.276Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:30.178Z"},"url":"https://mcp.waymark.network/r/bdf06170-37ac-4449-96f7-d3ec4b42e3d1"}