接入「使用 Ace Data Cloud 登录」（OAuth 2.0）

让你自己的产品支持「使用 Ace Data Cloud 登录」，并在用户授权后，代表用户读写其 Ace Data Cloud 资源（个人资料、API Token、订阅、用量、订单等）。底层是标准的 OAuth 2.0 授权码模式（Authorization Code）+ PKCE，与 GitHub / Google 登录的接法完全一致——你已有的任意 OAuth 客户端库都能直接用。

适合场景：你在做一个第三方应用 / Agent / MCP 客户端 / 自动化工作流，想让用户用 Ace Data Cloud 账号一键登录，并按需访问他在平台上的资源，而不必让用户手动复制粘贴 API Key。

名词 & 端点速查

所有端点都在 https://auth.acedata.cloud，可通过发现端点（Discovery）随时获取最新地址：

curl https://auth.acedata.cloud/.well-known/oauth-authorization-server

用途	端点
发现文档（Discovery）	`GET /.well-known/oauth-authorization-server`
用户授权页（浏览器跳转）	`GET https://auth.acedata.cloud/oauth2/authorize`
令牌端点（换 / 刷新 token）	`POST https://auth.acedata.cloud/oauth2/token`
撤销令牌	`POST https://auth.acedata.cloud/oauth2/revoke`
用户信息（UserInfo）	`GET https://auth.acedata.cloud/api/v1/users/me`
应用注册管理（自助）	`https://auth.acedata.cloud/user/oauth-apps`

支持的能力：response_type=code、grant_types=authorization_code, refresh_token、code_challenge_methods=S256, plain、客户端认证方式 client_secret_post（机密客户端）/ none（PKCE 公开客户端）。

权限范围（Scope）

按「最小权限」申请，用户会在授权页看到你申请的每一项权限。 身份类（OIDC 兼容）

Scope	含义	`/users/me` 返回字段
`openid`	用户唯一标识	`id`
`profile`	基础资料	`username`、`nickname`、`avatar`、`is_verified`、`date_joined`
`email`	邮箱	`email`
`phone`	手机号（敏感）	`phone`、`region`

平台资源类

Scope	含义
`applications:read` / `applications:write`	读 / 改用户的服务订阅与额度
`credentials:read` / `credentials:write`	读 / 创建撤销用户的 API Token
`usage:read`	读用户的调用历史
`orders:read` / `orders:write`	读订单 / 下单并发起支付

聚合类（自动展开）

Scope	展开为
`platform:read`	`applications:read` + `credentials:read` + `usage:read` + `orders:read`
`platform:write`	`applications:write` + `credentials:write` + `orders:write`
`platform`	`platform:read` + `platform:write`

特殊

Scope	含义
`offline_access`	颁发 Refresh Token（不申请则只下发 Access Token，过期需重新授权）

典型组合：第三方「一键登录」=openid profile；MCP / IDE 客户端需要自动配 Key =openid profile credentials:read credentials:write；完整管理台 =openid profile email platform offline_access。

第 1 步：注册一个 OAuth 应用

打开 auth.acedata.cloud/user/oauth-apps →「创建应用」，填写：

应用名称 / 描述 / Logo：会显示在用户的授权同意页。
客户端类型（Client Type）：
- 机密（confidential）——你有后端，能安全保管 client_secret（Web 服务、后端服务）。
- 公开（public）——纯前端 / 桌面 / CLI / 移动端，无法保管密钥，必须用 PKCE。
回调地址（Redirect URIs）：授权完成后用户被重定向回的地址，必须与你发起授权时传的 redirect_uri 完全一致，可填多个。
权限范围（Scopes）：勾选上一节里你需要的 scope。

保存后拿到 client_id；机密客户端还会一次性显示 client_secret——立刻保存，关闭后无法再次查看（可在详情页「轮换密钥 / Rotate Secret」重新生成，旧密钥立即失效）。

每个账号最多创建 20 个 OAuth 应用。

第 2 步：把用户重定向到授权页

在你的应用里，把用户浏览器跳转到授权页，带上查询参数：

https://auth.acedata.cloud/oauth2/authorize
  ?response_type=code
  &client_id=<你的 client_id>
  &redirect_uri=<你注册的回调地址>
  &scope=openid%20profile%20credentials:read
  &state=<随机防 CSRF 串>
  &code_challenge=<PKCE 挑战值>          # 公开客户端必填
  &code_challenge_method=S256            # 公开客户端必填

state：自己生成的随机串，回调时原样带回，用来防 CSRF，务必校验。
PKCE（公开客户端必做，机密客户端也推荐）：先生成随机 code_verifier，再计算 code_challenge = BASE64URL( SHA256( code_verifier ) )，把 code_challenge 放进授权 URL， code_verifier 自己留着第 4 步用。

用户登录并点击「同意」后，浏览器会被重定向回：

<redirect_uri>?code=<授权码>&state=<原样返回的 state>

若用户拒绝：<redirect_uri>?error=access_denied&error_description=...&state=...。

授权码有效期 10 分钟，且只能用一次。

第 3 步：用授权码换取令牌

在你的后端（机密客户端）或客户端（PKCE 公开客户端）用 code 调用令牌端点。 机密客户端（带 client_secret）：

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<上一步拿到的 code> \
  -d client_id=<你的 client_id> \
  -d client_secret=<你的 client_secret> \
  -d redirect_uri=<和第 2 步完全一致的回调地址>

公开客户端（PKCE，无 client_secret）：

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d client_id=<你的 client_id> \
  -d code_verifier=<第 2 步生成的 code_verifier> \
  -d redirect_uri=<回调地址>

成功返回（refresh_token 仅在申请了 offline_access 时出现）：

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "scope": "openid profile credentials:read",
  "refresh_token": "<JWT，仅 offline_access 时>"
}

access_token 是一个 JWT，内含 scope 声明；有效期 15 天（expires_in 秒数）。Refresh Token 有效期 30 天。

第 4 步：用 Access Token 调用接口

把令牌放进 Authorization: Bearer 头即可。 读取用户信息（UserInfo，字段按已授权 scope 过滤）：

curl https://auth.acedata.cloud/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"

调用平台资源接口（api.acedata.cloud，按 scope 鉴权）。例如已获 credentials:read：

curl https://api.acedata.cloud/api/v1/credentials/ \
  -H "Authorization: Bearer <access_token>"

平台后端会校验 JWT 里的 scope 声明——令牌只能访问用户授权过的资源。若访问了未授权的资源，会返回 403。

刷新令牌

Access Token 过期后，用 Refresh Token 换一对新令牌（需当初申请了 offline_access）：

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=<你的 refresh_token>

返回结构同第 3 步；scope 会从原授权中原样保留。刷新后旧 Refresh Token 失效（轮换），请保存新的。

撤销令牌

curl -X POST https://auth.acedata.cloud/oauth2/revoke \
  -d token=<access_token 或 refresh_token>

真实案例：我们自己的 MCP 服务器就是这么接的

Ace Data Cloud 的 15+ 个 MCP 服务器（NanoBanana、Midjourney、Suno、Seedance、Kling…）在 Claude Desktop / Cursor 里出现的「Sign in with Ace Data Cloud」连接，走的就是这套流程：它们都是注册为 公开（PKCE） 类型的 OAuth 应用，申请 credentials 相关 scope，用户授权后 MCP 服务器即可代表用户调用 api.acedata.cloud——无需用户手动粘贴 API Key。你的接法和它们完全一样。

常见错误

错误响应统一为 { "error": "<code>", "error_description": "<人类可读说明>" }：

error	含义 / 排查
`invalid_request`	缺少或非法参数（如没传 `code` / `client_id`）
`invalid_client`	`client_id` 不存在、应用被停用，或 `client_secret` 不对
`invalid_grant`	授权码不存在 / 已过期（>10 分钟）/ 已被用过 / PKCE 校验失败 / `redirect_uri` 与授权时不一致
`access_denied`	用户在授权页点了「拒绝」
`unsupported_grant_type`	`grant_type` 不是 `authorization_code` 或 `refresh_token`

限制速查

项	值
每账号最多 OAuth 应用数	20
授权码有效期	10 分钟，单次使用
Access Token 有效期	15 天
Refresh Token 有效期	30 天（轮换）
`redirect_uri`	必须与注册值精确匹配
`client_secret`	仅创建 / 轮换时显示一次，服务端以 SHA-256 哈希存储

​名词 & 端点速查

​权限范围（Scope）

​第 1 步：注册一个 OAuth 应用

​第 2 步：把用户重定向到授权页

​第 3 步：用授权码换取令牌

​第 4 步：用 Access Token 调用接口

​刷新令牌

​撤销令牌

​真实案例：我们自己的 MCP 服务器就是这么接的

​常见错误

​限制速查