接入「使用 Ace Data Cloud 登录」（OAuth 2.0）
内容提要
本文介绍如何为第三方应用接入“使用 Ace Data Cloud 登录”（OAuth 2.0 授权码模式+PKCE）。内容包括注册 OAuth 应用、获取授权码、换取令牌、调用接口及刷新/撤销令牌的完整流程，并列出权限范围、端点、常见错误和限制。适用于让用户一键登录并授权访问其平台资源，无需手动复制 API Key。
延伸解读
为什么推荐使用 PKCE
文章强调，公开客户端（纯前端、桌面、CLI、移动端）无法安全保管 client_secret，因此必须使用 PKCE。即使对于机密客户端，PKCE 也被推荐使用。PKCE 通过动态生成的 code_verifier 和 code_challenge 替代静态密钥，避免了密钥泄露风险，同时简化了授权流程。对于开发者而言，理解 PKCE 的机制有助于在多种客户端类型中安全地实现 OAuth 2.0 登录。
权限范围的最小化原则
文章建议按“最小权限”申请 scope，用户会在授权页看到每一项权限。这有助于保护用户隐私，减少因过度授权带来的安全风险。例如，仅需登录时可只申请 openid 和 profile；而需要自动配置 API Key 的 MCP 客户端则需额外申请 credentials 相关权限。开发者应根据实际需求谨慎选择 scope，避免请求不必要的敏感权限（如 email、phone），以提升用户信任和通过率。
令牌轮换与安全注意事项
文章指出，Refresh Token 有效期为 30 天，且每次刷新后旧令牌立即失效（轮换机制）。这意味着开发者必须妥善保存新的 Refresh Token，并处理并发刷新时的潜在冲突。此外，client_secret 仅在创建或轮换时显示一次，服务端以哈希存储，因此一旦丢失需立即轮换。这些安全细节对于生产环境中的稳定运行至关重要，开发者应建立相应的令牌管理策略。
Q&A
如何为第三方应用接入“使用 Ace Data Cloud 登录”？
接入流程包括：1. 在 auth.acedata.cloud/user/oauth-apps 注册 OAuth 应用，获取 client_id（机密客户端还有 client_secret）；2. 将用户重定向到授权页，携带 response_type=code、client_id、redirect_uri、scope、state 和 PKCE 参数；3. 用户授权后，用授权码换取 access_token（和可选的 refresh_token）；4. 使用 access_token 调用用户信息接口和平台资源接口。
Ace Data Cloud 的 OAuth 2.0 支持哪些授权模式和客户端类型？
支持 OAuth 2.0 授权码模式（Authorization Code）+ PKCE。客户端类型分为机密（confidential）和公开（public）。机密客户端使用 client_secret 进行认证，公开客户端使用 PKCE（code_challenge_method 支持 S256 和 plain）。
在 Ace Data Cloud OAuth 中，如何申请权限范围（Scope）？有哪些常用 Scope？
在注册应用时勾选所需 Scope，用户授权时会看到申请的权限。常用 Scope 包括：身份类（openid、profile、email、phone），平台资源类（applications:read/write、credentials:read/write、usage:read、orders:read/write），聚合类（platform:read、platform:write、platform），以及特殊 Scope offline_access（用于获取 Refresh Token）。典型组合：一键登录用 openid profile；MCP 客户端用 openid profile credentials:read credentials:write；完整管理台用 openid profile email platform offline_access。
如何获取 Access Token 和 Refresh Token？有效期分别是多久？
通过授权码换取令牌：在令牌端点 POST https://auth.acedata.cloud/oauth2/token，携带 grant_type=authorization_code、code、client_id、redirect_uri（机密客户端还需 client_secret，公开客户端需 code_verifier）。成功返回 access_token（JWT），有效期 15 天；如果申请了 offline_access，还会返回 refresh_token，有效期 30 天。
如何使用 Access Token 调用 Ace Data Cloud 的 API？
将 Access Token 放在 HTTP 请求的 Authorization: Bearer 头中。例如，获取用户信息：curl https://auth.acedata.cloud/api/v1/users/me -H "Authorization: Bearer <access_token>"。调用平台资源接口（如 api.acedata.cloud）时，后端会校验 JWT 中的 scope 声明，只能访问用户授权的资源，否则返回 403。
如何刷新和撤销 Access Token？
刷新：使用 Refresh Token 调用令牌端点，grant_type=refresh_token，携带 refresh_token，返回新的 access_token 和 refresh_token（旧 refresh_token 失效）。撤销：调用 POST https://auth.acedata.cloud/oauth2/revoke，携带 token 参数（access_token 或 refresh_token）。
Ace Data Cloud OAuth 的常见错误有哪些？如何排查？
常见错误包括：invalid_request（参数缺失或非法）、invalid_client（client_id 不存在或 client_secret 错误）、invalid_grant（授权码无效、过期、已使用或 PKCE 校验失败）、access_denied（用户拒绝）、unsupported_grant_type（grant_type 不支持）。错误响应统一为 { "error": "<code>", "error_description": "<说明>" }，可根据 error 字段排查。
Ace Data Cloud OAuth 有哪些限制？
限制包括：每个账号最多创建 20 个 OAuth 应用；授权码有效期 10 分钟且只能使用一次；Access Token 有效期 15 天；Refresh Token 有效期 30 天且轮换；redirect_uri 必须与注册值精确匹配；client_secret 仅在创建或轮换时显示一次，服务端以 SHA-256 哈希存储。
