invalid_grant api auth_error ai_generated true

OAuth2 error: invalid_grant — refresh token expired or revoked

ID: api/oauth2-invalid-grant-refresh-token-expired

Also available as: JSON · Markdown · 中文
85%Fix Rate
85%Confidence
1Evidence
2024-03-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
OAuth 2.0 (RFC 6749) active — — —
Google OAuth 2.0 (2023+) active — — —
Auth0 OIDC (2024) active — — —

Root Cause

The refresh token used to obtain a new access token has been revoked, expired, or used beyond its rotation limit, causing the authorization server to reject the grant.

generic

中文

用于获取新访问令牌的刷新令牌已被撤销、过期或超出轮换限制，导致授权服务器拒绝授权。

Official Documentation

https://datatracker.ietf.org/doc/html/rfc6749#section-5.2

Workarounds

  1. 85% success Implement refresh token rotation: after each successful token refresh, invalidate the old refresh token and issue a new one. In code, use a library like `oauthlib` or `google-auth` that handles rotation automatically. Example: `credentials.refresh(request)` with `google.oauth2.credentials`. 
    Implement refresh token rotation: after each successful token refresh, invalidate the old refresh token and issue a new one. In code, use a library like `oauthlib` or `google-auth` that handles rotation automatically. Example: `credentials.refresh(request)` with `google.oauth2.credentials`.
  2. 90% success Store refresh tokens securely and monitor their expiration. If the error occurs, prompt the user to re-authenticate via the full OAuth flow. Example: catch `RefreshError` and redirect to the authorization endpoint. 
    Store refresh tokens securely and monitor their expiration. If the error occurs, prompt the user to re-authenticate via the full OAuth flow. Example: catch `RefreshError` and redirect to the authorization endpoint.
  3. 80% success Check if the refresh token has been revoked by inspecting the authorization server's token introspection endpoint. Example: `POST /introspect` with `token=<refresh_token>` and `token_type_hint=refresh_token`. 
    Check if the refresh token has been revoked by inspecting the authorization server's token introspection endpoint. Example: `POST /introspect` with `token=<refresh_token>` and `token_type_hint=refresh_token`.

中文步骤

  1. 实现刷新令牌轮换：每次成功刷新令牌后，使旧刷新令牌失效并颁发新令牌。使用像 `oauthlib` 或 `google-auth` 这样的库自动处理轮换。示例：`credentials.refresh(request)` 配合 `google.oauth2.credentials`。
  2. 安全存储刷新令牌并监控其过期时间。如果出现此错误，提示用户通过完整的 OAuth 流程重新认证。示例：捕获 `RefreshError` 并重定向到授权端点。
  3. 通过检查授权服务器的令牌内省端点来验证刷新令牌是否被撤销。示例：`POST /introspect` 参数 `token=<refresh_token>` 和 `token_type_hint=refresh_token`。

Dead Ends

Common approaches that don't work:

  1. 90% fail

    The token is already expired or revoked; reusing it will still fail.

  2. 70% fail

    The underlying issue (e.g., token rotation limit or revocation) persists, causing the new refresh token to fail again.

  3. 80% fail

    The error is a permanent grant rejection, not a transient network issue; retries will not succeed.