接入 Ace Data Cloud OAuth 2.0

让用户授权你的应用访问其 Ace Data Cloud 个人资料、服务订阅、API Key、用量或订单。使用标准 Authorization Code + S256 PKCE：应用打开授权页，用户同意后收到一次性 code，再换取 OAuth access token。 OAuth access token 用于访问账户资源接口；调用模型 API 使用相应的 API Key。OAuth 授权不会自动创建 API Key、开通服务或增加余额。

选择接入方式

方式	适用场景	授权完成后
标准 OAuth 跳转	独立网站、桌面或移动客户端；嵌入网站自行发起授权	浏览器回到应用登记的 `redirect_uri`，应用处理 `code` 和 `state`
Studio 网站组件授权	网站嵌入 Studio 首页，并希望使用访客当前的 Studio 账号	Studio 向应用发送授权结果消息，应用不跳转，原页面保留

标准跳转不要求 embed=studio、embed_origin 或 postMessage。Studio 组件模式由宿主创建授权页并维护消息桥；第三方按本文末尾的组件协议接入，不要自行拼接这两个参数。

端点与发现文档

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

用途	地址
浏览器授权页	`https://auth.acedata.cloud/oauth2/authorize`
换取／刷新 OAuth token	`POST https://auth.acedata.cloud/oauth2/token`
提交撤销请求	`POST https://auth.acedata.cloud/oauth2/revoke`
当前用户信息	`GET https://auth.acedata.cloud/api/v1/users/me`
OAuth 应用管理页面	OAuth 应用
已登录用户的应用列表／注册接口	`https://auth.acedata.cloud/api/v1/oauth2/applications/`
授权页使用的公开应用资料	`GET https://auth.acedata.cloud/api/v1/oauth2/application/<client_id>/`
用户的现有 API Key	`GET https://platform.acedata.cloud/api/v1/credentials/?user_id=<用户ID>&limit=100`

应用管理接口需要账户登录认证，不是匿名动态注册（DCR）接口。MCP 服务自己的发现／注册地址与本表中的账户 OAuth 端点是不同入口；连接具体 MCP 时按该服务的文档和发现结果操作。发现文档用于获取端点与协议能力。当前流程返回 OAuth token，不返回 id_token；不要仅因为存在 openid scope 就按完整 OpenID Connect 登录流程处理。

权限范围：使用当前 scope 名称

scope 是空格分隔的、区分大小写的权限名称。新应用使用 profile:read、email:read、phone:read 等具体权限。

从哪里获取可申请的权限

登录后，OAuth 应用列表接口 GET /api/v1/oauth2/applications/ 返回 available_scopes；应用管理页面的权限选择器使用同一份目录。这是普通自助应用应采用的可选范围。 Discovery 的 scopes_supported 包含平台识别的全部权限名称，不代表你的应用可以申请其中的每一项。 实际授权同时检查：

权限是否允许委托给该应用类型；
权限是否已登记在这个 OAuth 应用的允许范围内；
当前用户是否拥有请求的权限。

未知、未登记、不允许委托或用户不具备的权限会返回 invalid_scope。授权码兑换及刷新时也会重新检查，不会自动补齐或提升权限。

普通自助应用可选权限

以下为当前目录（2026-10-09）；接入时以 available_scopes 为准。

Scope	用途
`profile:read` / `profile:write`	读取／更新个人资料
`email:read`	读取邮箱
`phone:read`	读取手机号及地区
`billing-profile:read` / `billing-profile:write`	读取／管理账单资料
`applications:read` / `applications:write`	读取／管理服务订阅
`credentials:read` / `credentials:write`	读取／管理 API Key
`usage:read`	读取调用记录
`orders:read` / `orders:write`	读取／创建和管理订单
`auto-recharge:read` / `auto-recharge:write`	读取／管理自动充值设置
`recharge-cards:redeem`	兑换充值卡
`coin:read`	读取代币相关信息
`distribution:read`	读取分销信息
`connections:read` / `connections:write`	读取／管理连接
`skills:read` / `skills:write`	读取／管理技能
`openid`	当前实现也允许 UserInfo 返回基础资料；不返回 ID Token
`offline_access`	请求 refresh token，以便在 access token 过期后刷新

例如，只读取个人资料用 profile:read；需要邮箱再加 email:read；读取已有 API Key 用 profile:read credentials:read。只有确实需要创建或修改 Key 时才申请 credentials:write，需要刷新时再加 offline_access。部分权限仅供平台批准的受信任应用使用，例如 sites:read、sites:write、platform-tokens:read；另一些权限不开放给普通第三方 OAuth 应用。客户端类型 public／confidential 描述的是能否保管 secret，与应用是否受信任无关。自助创建应用不能自行开启受信任权限。 account 是指定的官方账户管理 MCP 使用的账户权限选择器，不是第三方应用的“全部权限”scope，不能与其他 scope 混用。第三方应明确列出需要的具体权限。

从旧文档迁移

旧写法	当前接法
`profile`	`profile:read`
`email`	`email:read`
`phone`	`phone:read`
`platform`、`platform:read`、`platform:write`	逐项列出实际需要的具体权限，没有通用的“全选”替代值

旧名称不作为兼容别名接受。同步更新 OAuth 应用登记的 scopes、授权 URL 和自己的权限判断；修改应用配置不会给已签发 token 增加权限，需要用户重新授权。

第 1 步：注册 OAuth 应用

打开 OAuth 应用管理，创建应用并填写：

名称、描述、应用 Logo：显示在授权页的应用一侧。
客户端类型：纯前端、移动或桌面客户端选择 Public；能在后端保管 secret 的服务选择 Confidential。
回调地址：生产环境使用 HTTPS，并登记应用真正处理回调的完整 URL。
权限：从页面提供的目录中选择实际需要的 scopes。

保存 client_id。Confidential 客户端将 client_secret 保存在服务器端，不能放到 HTML、前端构建变量或 URL 中。Public 客户端换取 token 不使用 secret，即使注册响应包含该字段，也不能把它当作客户端可以保密的凭据。 redirect_uri 在注册、授权和换 token 时必须精确一致，包括路径、尾部斜杠和查询参数。每个账号最多创建 20 个应用。Secret 只在创建／轮换时显示；轮换后旧 secret 无法继续进行需要客户端认证的兑换。

第 2 步：按钮发起授权

每次点击连接，生成新的随机 state 与 code_verifier，计算：

code_challenge = BASE64URL(SHA256(code_verifier))

将 state、verifier 和回调地址保存在应用自己的会话中，再用 URL 编码后的参数打开授权页：

https://auth.acedata.cloud/oauth2/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=<完整回调地址>
  &scope=profile%3Aread%20credentials%3Aread
  &state=<本次随机值>
  &code_challenge=<本次S256挑战值>
  &code_challenge_method=S256

Public 客户端必须发送 S256 PKCE。虽然 Discovery 还列出 plain，Public 客户端不能使用它。Confidential 客户端也建议使用 S256；发起授权时使用了 PKCE，兑换时就必须提交对应 verifier。用户同意后回到 redirect_uri，查询参数包含 code 和原样返回的 state。拒绝时返回 error=access_denied、错误说明及 state。处理回调前先验证 state 与本次会话匹配。授权码有效期为 10 分钟，且只能兑换一次；失败后应重新发起连接，不要反复刷新旧回调 URL。

第 3 步：换取 OAuth token

Public 客户端直接从浏览器或客户端兑换；Confidential 客户端在自己的后端兑换。请求正文支持表单编码，以下变量代表应用本次授权得到的数据：

curl https://auth.acedata.cloud/oauth2/token \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

Confidential 客户端还需在服务器端增加 client_secret 表单字段。当前支持 client_secret_post，不要将 HTTP Basic 客户端认证当作已支持的方式。成功响应中读取 access_token、token_type、expires_in 和实际授予的 scope。只有请求并获准 offline_access 才有 refresh_token。不要把 OAuth access token 当作模型 API 的 API Key，也不要把 token、verifier 或授权码写入日志、分析事件或分享链接。

第 4 步：读取用户信息和 API Key

先使用 OAuth access token 请求 UserInfo：

curl https://auth.acedata.cloud/api/v1/users/me \
  -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN"

返回字段取决于 scope：id 是用户标识；profile:read 或 openid 可读取基础资料（如 username、nickname、avatar、is_verified、date_joined、registration_method）；邮箱需要 email:read，手机号及地区需要 phone:read。不要依赖未授权字段总是存在。需要已有 API Key 且获准 credentials:read 时，用 UserInfo 的 id 作为筛选条件：

curl "https://platform.acedata.cloud/api/v1/credentials/?user_id=$USER_ID&limit=100&offset=0" \
  -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN"

返回列表使用 count 和 items，Key 字段是 items[*].token，不是 data[0].value。user_id=me 不是这个接口的有效用户 ID。多页数据按 offset／limit 继续读取，不要把第一页当作全部凭证。根据应用、服务和有效状态选择适用的凭证，不要盲目取第一条。列表为空不代表授权失败；用户可能尚未创建适用的 Key。OAuth access token 的权限控制与 API Key 自身的服务范围、额度和过期条件是不同约束。允许读取 API Key 意味着第三方能够保存并使用它。撤销 OAuth 请求或清除应用登录状态不会使已复制的 API Key 失效；需要用户在凭证管理中单独撤销或轮换该 Key。

可运行的 Public / PKCE 浏览器示例

将下列页面部署到你登记的 REDIRECT_URI，替换 CLIENT_ID 和回调地址。按钮发起标准授权，回到同一页面后读取个人资料和已有 Key 数量。示例不显示、不持久化 Key；生产应用根据实际用途消费结果。先在独立浏览器页面验证，再按后面的 iframe 要求验收。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>连接 Ace Data Cloud</title>
<button id="connect" type="button">连接账号</button>
<p id="status" role="status">尚未连接</p>
<script type="module">
const CLIENT_ID = '替换为你的 client_id';
const REDIRECT_URI = 'https://your-app.example/connect';
const AUTH_ORIGIN = 'https://auth.acedata.cloud';
const button = document.querySelector('#connect');
const status = document.querySelector('#status');
const storageKey = state => `ace-oauth:${state}`;

function base64url(bytes) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

async function requestJson(url, options = {}) {
  const response = await fetch(url, { ...options, signal: AbortSignal.timeout(15000) });
  if (!response.ok) throw new Error(`接口返回 HTTP ${response.status}`);
  return response.json();
}

button.addEventListener('click', async () => {
  button.disabled = true;
  try {
    const state = base64url(crypto.getRandomValues(new Uint8Array(24)));
    const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
    sessionStorage.setItem(storageKey(state), JSON.stringify({
      verifier, redirectUri: REDIRECT_URI, createdAt: Date.now()
    }));
    const url = new URL('/oauth2/authorize', AUTH_ORIGIN);
    url.search = new URLSearchParams({
      response_type: 'code', client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,
      scope: 'profile:read credentials:read', state,
      code_challenge: base64url(new Uint8Array(digest)), code_challenge_method: 'S256'
    }).toString();
    window.location.assign(url);
  } catch {
    status.textContent = '无法开始连接，请检查浏览器存储设置后重试。';
    button.disabled = false;
  }
});

async function handleCallback() {
  const url = new URL(window.location.href);
  if (!url.searchParams.has('code') && !url.searchParams.has('error')) return;
  button.disabled = true;
  try {
    const state = url.searchParams.get('state');
    const raw = state && sessionStorage.getItem(storageKey(state));
    if (!raw) throw new Error('授权会话不匹配，请重新连接。');
    const transaction = JSON.parse(raw);
    const age = Date.now() - transaction.createdAt;
    if (!Number.isFinite(age) || age < 0 || age > 10 * 60 * 1000 ||
        transaction.redirectUri !== REDIRECT_URI || !transaction.verifier) {
      throw new Error('授权会话已失效，请重新连接。');
    }
    sessionStorage.removeItem(storageKey(state));
    const code = url.searchParams.get('code');
    const denied = url.searchParams.get('error');
    for (const key of ['code', 'state', 'error', 'error_description']) url.searchParams.delete(key);
    window.history.replaceState({}, '', url);
    if (denied) throw new Error('未完成授权，可以重新连接。');
    if (!code) throw new Error('回调缺少授权码，请重新连接。');
    status.textContent = '正在连接…';
    const token = await requestJson(`${AUTH_ORIGIN}/oauth2/token`, {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: 'authorization_code', client_id: CLIENT_ID,
        redirect_uri: REDIRECT_URI, code, code_verifier: transaction.verifier
      })
    });
    if (!token.access_token) throw new Error('未取得授权令牌。');
    const headers = { Authorization: `Bearer ${token.access_token}` };
    const profile = await requestJson(`${AUTH_ORIGIN}/api/v1/users/me`, { headers });
    if (!profile.id) throw new Error('未取得用户标识。');
    const keysUrl = new URL('https://platform.acedata.cloud/api/v1/credentials/');
    keysUrl.search = new URLSearchParams({ user_id: profile.id, limit: '100' }).toString();
    const credentials = await requestJson(keysUrl, { headers });
    if (!Array.isArray(credentials.items)) throw new Error('凭证列表格式不符。');
    const keyCount = credentials.items.filter(item => typeof item.token === 'string' && item.token).length;
    status.textContent = `已连接 ${profile.nickname || profile.username || profile.id}；本页有 ${keyCount} 条 API Key。`;
  } catch (error) {
    status.textContent = `连接未完成：${error.message || '网络异常'} 请重新点击连接。`;
  } finally {
    button.disabled = false;
  }
}

await handleCallback();
</script>
</html>

示例的回调和入口必须处于相同来源、同一浏览器标签页／iframe，才能读取原先保存的 sessionStorage。生产应用应在自己的会话方案中管理令牌，处理过期，并在收到响应后清除授权 URL 参数；页面主界面应先渲染，网络失败只影响连接状态。

白标网站中的 iframe

客户网站自行跳转授权页

使用标准 OAuth 参数和自己的回调处理即可；window.location.assign() 导航当前 iframe，父页面保留在白标域名。无需为了图标添加 embed=studio 或实现 Studio 消息协议。需要满足以下条件：

应用页和回调页使用 HTTPS，实际可访问，并允许白标父域通过 iframe 嵌入；检查双方的 Content-Security-Policy: frame-ancestors 与 X-Frame-Options。
sandbox 允许页面所需的脚本、表单和来源／存储能力。支持弹窗登录时还需要相应的弹窗能力；优先使用 Studio 提供的 Website 组件配置。
浏览器允许当前嵌入场景使用授权状态所需的存储。白标站登录状态与 AuthFrontend 登录状态可能不同，不应假设登录了白标站就已登录授权页。
回调中的 token 交换服务可用，跨域请求允许应用来源；DNS、CORS、HTTP 错误都必须展示可重试的状态，不能让整个页面停止渲染。

授权页左侧读取 OAuth 应用 Logo；右侧在浏览器可提供父来源且父域通过已验证站点校验时读取该 Site 的 favicon／logo，否则显示默认图标。这只决定品牌展示，不建立登录会话，也不会向客户页面提供账户权限。 当前限制：普通 OAuth 在 iframe 内需要重新登录时，登录完成后继续回到授权页的流程尚有缺口。 上线前必须分别验收“Auth 已登录”和“Auth 未登录／已过期”。在该缺口修复并验证前，首次登录可使用独立页面完成标准 OAuth，或采用下面的 Studio 组件授权；不要仅靠已登录的测试结果承诺所有 iframe 场景可用。

使用 Studio 当前账号授权

在 Studio「设置 → 首页 → 网站组件」开启 OAuth，填写 client_id 和已登记的回调地址。网站与回调必须使用相同 HTTPS 来源，并与 Studio 来源不同。第三方页面需要：

向确切的父站点 origin 发送 acedatacloud:oauth:ready，接收并校验 acedatacloud:oauth:init。
按钮生成 state 与 PKCE verifier，发送 acedatacloud:oauth:authorize（state、S256 challenge）；verifier 留在自己页面内。
校验父窗口、origin 和 state，处理 acedatacloud:oauth:result 中的 code 或 error，并按标准 token 端点兑换。

Studio 在组件区域显示授权页，用户同意后以消息返回授权码，应用不需要跳转。没有登录时返回 login_required，拒绝时返回 access_denied，等待超时返回 authorization_timeout。账号变化会重建应用 iframe 并取消未完成授权。组件当前请求 profile:read credentials:read，不包含 offline_access。不要假设一定能收到 refresh token。embed=studio、embed_origin 由 Studio 宿主与授权页维护，客户页面只需遵守消息协议。完整按钮示例见 Studio 网站组件 OAuth 接入指南。

生命周期、刷新和撤销

Access token 的默认有效期为 15 天，应以每次响应的 expires_in 安排刷新或重新授权；refresh token 默认 30 天，期限受服务配置影响。不要把这两个值硬编码为永久承诺。获准 offline_access 后，可调用：

curl https://auth.acedata.cloud/oauth2/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode "refresh_token=$OAUTH_REFRESH_TOKEN"

刷新会返回新的 token，应用应保存最新值。刷新时会检查应用是否仍有效、用户是否可用、权限是否仍获准。失败时清除自己的连接状态并重新授权。 当前 OAuth 刷新实现不保证旧 refresh token 在刷新后立即失效。 不要将拿到新 token 当作旧 token 已被撤销，也不要以轮换 secret 代替终止既有 token。撤销请求的调用方式是：

curl https://auth.acedata.cloud/oauth2/revoke \
  --data-urlencode "token=$OAUTH_ACCESS_TOKEN"

当前撤销端点返回 HTTP 200，但没有实现已签发 JWT 的即时失效。 应用应清除自己保存的 token，不能把 200 当作所有已签发 token 或 API Key 已失效的证明。涉及已泄露或已复制的 API Key，应单独撤销或轮换对应凭证。

常见错误与验收

现象／错误	排查
`invalid_scope`	使用现行权限名；检查应用登记范围、委托限制及用户权限。Discovery 全目录不是应用可选目录
`invalid_request`	必填参数、精确回调地址、Public 客户端 S256 challenge 和 method
`invalid_client`	client ID、应用状态、Confidential 客户端 secret；检查是否错误使用了 Basic 认证
`invalid_grant`	code 过期／已消费、verifier 或 redirect URI 不匹配；刷新时还检查应用和权限变化
`access_denied`	用户拒绝，恢复连接按钮，不要循环弹出授权
`unsupported_grant_type`	当前支持 `authorization_code`、`refresh_token`
HTTP 401／403	区分无效登录态、token、授权 scope 与资源本身的访问权限
`Failed to fetch`、DNS／CORS 错误	核对真实请求主机及客户后端可用性，不能归因于“用户没有 Key”
已授权但读不到 Key	使用 `platform.acedata.cloud`、真实 user ID、`items[*].token`；区分空列表、分页和失败响应
授权返回后整页空白	页面先渲染；回调、token、UserInfo 和凭证请求各自处理错误；不要让初始化异常停止全页
iframe 登录后不继续	按上文现有限制处理，测试未登录、过期、拒绝和重新连接场景

交付前至少验证：正确回调、拒绝、错误 state、过期／已消费 code、无 Key、网络失败、token 过期、所需 scope 缺失，以及 iframe 场景下的首次登录与账号切换。测试证据中不要保存完整 code、token 或 API Key。

入门

核心概念

生态集成

AI 聊天

AI 图像

AI 视频

AI 音频

网络与数据

验证码

身份验证

高级

Coding

更多指南

接入 Ace Data Cloud OAuth 2.0

选择接入方式

端点与发现文档

权限范围：使用当前 scope 名称

从哪里获取可申请的权限

普通自助应用可选权限

从旧文档迁移

第 1 步：注册 OAuth 应用

第 2 步：按钮发起授权

第 3 步：换取 OAuth token

第 4 步：读取用户信息和 API Key

可运行的 Public / PKCE 浏览器示例

白标网站中的 iframe

客户网站自行跳转授权页

使用 Studio 当前账号授权

生命周期、刷新和撤销

常见错误与验收

​选择接入方式

​端点与发现文档

​权限范围：使用当前 scope 名称

​从哪里获取可申请的权限

​普通自助应用可选权限

​从旧文档迁移

​第 1 步：注册 OAuth 应用

​第 2 步：按钮发起授权

​第 3 步：换取 OAuth token

​第 4 步：读取用户信息和 API Key

​可运行的 Public / PKCE 浏览器示例

​白标网站中的 iframe

​客户网站自行跳转授权页

​使用 Studio 当前账号授权

​生命周期、刷新和撤销

​常见错误与验收

选择接入方式

端点与发现文档

权限范围：使用当前 scope 名称

从哪里获取可申请的权限

普通自助应用可选权限

从旧文档迁移

第 1 步：注册 OAuth 应用

第 2 步：按钮发起授权

第 3 步：换取 OAuth token

第 4 步：读取用户信息和 API Key

可运行的 Public / PKCE 浏览器示例

白标网站中的 iframe

客户网站自行跳转授权页

使用 Studio 当前账号授权

生命周期、刷新和撤销

常见错误与验收