Implement refresh token rotation with reuse detection

Steps

1. Issue a new refresh token every time a refresh token is used (rotation); immediately invalidate the previously used refresh token upon issuing the replacement.
2. Group related refresh tokens into a token family by storing a shared family_id alongside each token record in your database.
3. 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.
4. 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.
5. Return an appropriate error (e.g., invalid_grant) to the client when reuse is detected; do not silently ignore the event.
6. Log reuse detection events with client IP, user id, and token family id for security monitoring and incident response.