Gmail API OAuth2认证报invalid_grant失效原因及预防方案咨询

你遇到的invalid_grant错误是Google OAuth授权体系的典型凭证失效问题，结合你项目闲置两三个月的场景，具体失效原因按优先级排序如下：

PHP Fatal error: Uncaught Google\Service\Exception: {
"error": "invalid_grant",
"error_description": "Bad Request"
}

• 测试态OAuth应用Refresh Token过期：如果你的GCP项目OAuth同意屏幕处于「测试」模式时，用户授权生成的Refresh Token最长有效期仅为7天，且项目连续30天无API调用记录时，所有授权凭证会被自动回收。你闲置两三个月远超过有效期，旧Refresh Token无法换取新的Access Token，就会抛出该错误。
• 旧OAuth Client ID被安全冻结：GCP会对长期无活跃调用的Client ID做安全冻结处理，避免闲置凭证被滥用，也会触发该报错。
• 授权权限变更：如果当初授权应用访问的Gmail账户后续修改了密码、开启了两步验证、手动撤销了应用访问权限，也会导致旧凭证直接失效。

• 将OAuth同意屏幕升级为「发布」状态：发布状态的OAuth应用，只要用户不手动撤销授权，Refresh Token不会有7天有效期限制，也不会因短期无活跃调用被自动回收。
• 新增Token自动刷新逻辑：在PHP脚本中新增异常捕获逻辑，当检测到invalid_grant错误时，自动触发重新授权流程获取新的Token并更新本地存储的凭证，避免程序直接中断。
• 不要随意修改OAuth核心配置：项目上线后不要轻易修改OAuth Client ID的重定向URI、申请的API作用域、同意屏幕权限列表等核心配置，修改后所有历史授权都会直接失效。
• 新增低频次心跳任务：对于长期闲置的副项目，可以配置每月一次的定时任务调用一次Gmail API，保证项目不会被判定为非活跃项目，避免凭证被自动回收。

内容的提问来源于stack exchange，提问作者ManoS