接入文档

通过 OAuth 2.0 授权码模式，让用户用 Naicha 账号登录你的产品。

1 登录开放平台→ 2 申请应用→ 3 获取 App ID / Secret→ 4 配置回调地址→ 5 接入登录→ 6 上线

在开发者中心登录并申请应用，选择客户端类型（网站 / 桌面 / App / 小程序 / 设备）。
填写授权回调地址（回调地址必须在白名单内，支持多个）。
审核通过后获得 App ID 与 App Secret（Secret 只显示一次，请保存到后端）。
按下方「接入示例」把登录能力接入你的产品。

申请应用（详细步骤）

注册 / 登录 Naicha 账号中心（登录 · 注册）。
进入「开放平台 → 开发者中心」，点击「申请应用」。如平台开启开发者付费入驻 / 实名认证要求，需先完成入驻。
填写应用信息：应用名称、简介、客户端类型（网站 / 桌面 / App / 小程序 / 设备）、首页地址（必填，授权页点击应用名会跳转到这里）、授权回调地址（可填多个，域名白名单需与回调地址域名一致）。
提交后平台审核。通过后应用状态变为「已上线」，即可开始接入。
在「我的应用」列表 / 详情页获取 App ID；App Secret 在详情页仅显示一次，请立即保存到后端环境变量，切勿写进前端代码或客户端安装包。

用户在你的网站点击「使用 Naicha 账号登录」 ↓ 跳转账号中心：/oauth/authorize?app_id=…&redirect_uri=…&state=… ↓（未登录则先在账号中心登录，已登录则直接跳过 = 免登录）账号中心重定向回：redirect_uri?code=一次性授权码&state=… ↓ 你的后端用 code + App Secret 换 access_token（服务端调用） ↓ 用 access_token 调 userinfo 获取 uid / 昵称 / 头像，建立本地会话

接口	方法	说明
/oauth/authorize	GET	网页授权入口（302 跳转，支持 code_challenge / scope）
/oauth/token	POST	code + app_secret（或 code_verifier / PKCE）换 access_token
/api/oauth/userinfo	GET	Bearer token 拉取用户信息（按 scope 过滤字段）
/api/oauth/validate	POST	校验 token 有效性（含封禁/停用状态）
/api/oauth/revoke	POST	撤销 token
/api/oauth/qr/start	POST	桌面扫码登录：申请扫码会话，返回 scan_id + qr_url
/oauth/qr/:scan_id	GET	手机扫码后的确认页（登录 + 确认授权）
/api/oauth/qr/:scan_id/status	GET	桌面端轮询：confirmed 时返回一次性 code

scope 参数（空格分隔，可选）：login（默认：用户名/昵称/头像）· email（+邮箱）· phone（+手机号）· profile（全部资料）

authorize 请求参数

参数	必填	说明
app_id	是	你的应用 App ID
redirect_uri	是	授权回调地址，必须与申请时填写一致（协议/端口/路径完全匹配，或命中回调域名白名单）
state	建议	随机字符串，回调时原样返回，用于防 CSRF 伪造回跳
scope	否	权限范围，空格分隔，如 `login email`
code_challenge	PKCE 时	PKCE 的 S256 摘要（App/桌面端必用，可免 secret）
code_challenge_method	PKCE 时	固定 `S256`

token 请求参数（POST /oauth/token）

参数	必填	说明
app_id	是	应用 App ID
app_secret	授权码模式	应用密钥（仅服务端调用；PKCE 流程传 code_verifier 可省略）
code	是	授权码，一次性，10 分钟内有效
code_verifier	PKCE 时	生成 code_challenge 时使用的原始随机串

成功响应格式

POST /oauth/token
→ 200 {
  "ok": true,
  "access_token": "eyJhbGciOiJIUzI1NiJ9.xxxx",
  "token_type": "Bearer",
  "expires_in": 2592000,       // 有效期秒数，默认 30 天（平台可配置）
  "scope": "login email",
  "user": {
    "uid": 10001,              // 用户唯一 ID，跨所有接入应用一致
    "username": "demo",
    "nickname": "演示用户",
    "avatar": "https://.../avatar.png",
    "email": "demo@naicha.cloud"  // 仅授权 email/phone/profile 时出现
  }
}

之后调用 /api/oauth/userinfo 时，请求头带 Authorization: Bearer <access_token>。

userinfo 返回字段

字段	类型	说明
uid	number	用户唯一 ID（跨应用一致，可用作本地用户主键）
username	string	登录名（唯一）
nickname	string	昵称（未设置时等于 username）
avatar	string	头像 URL（可能为空，为空请展示默认头像）
email	string	仅授权 `email` / `profile` 时返回
phone	string	仅授权 `phone` / `profile` 时返回

错误响应格式

→ 400 { "ok": false, "error": "回调地址不在白名单", "code": 400 }
→ 401 { "ok": false, "error": "token 无效或已过期",  "code": 401 }

① 前端：登录按钮（跳转账号中心授权）

// 点击「使用 Naicha 账号登录」
const state = Math.random().toString(36).slice(2);   // 防 CSRF，存会话
location.href = 'https://账号中心域名/oauth/authorize?app_id=YOUR_APP_ID'
  + '&redirect_uri=' + encodeURIComponent('https://yoursite.com/oauth/cb')
  + '&state=' + state;

② 回调 /oauth/cb：后端换 token 并拉用户

// Node.js（Express）示例
const code = req.query.code;                       // 一次性授权码
const r = await fetch('https://账号中心域名/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ app_id: 'YOUR_APP_ID', app_secret: 'YOUR_SECRET', code }),
});
const { access_token, user } = await r.json();
// user = { uid, username, nickname, avatar }；建立你的本地登录态即可

③ Python 示例

import requests

r = requests.post('https://账号中心域名/oauth/token', json={
    'app_id': 'YOUR_APP_ID', 'app_secret': 'YOUR_SECRET', 'code': code})
token = r.json()['access_token']

user = requests.get('https://账号中心域名/api/oauth/userinfo',
    headers={'Authorization': 'Bearer ' + token}).json()

④ Go 示例

resp, _ := http.PostForm("https://账号中心域名/oauth/token", url.Values{
    "app_id": {"YOUR_APP_ID"}, "app_secret": {"YOUR_SECRET"}, "code": {code},
})
var d struct{ AccessToken string `json:"access_token"` }
json.NewDecoder(resp.Body).Decode(&d)
// 用 d.AccessToken 调 /api/oauth/userinfo 拉用户

⑤ 定时校验用户是否仍有效（封号/停用联动）

POST /api/oauth/validate  { "app_id","app_secret","token" }
→ { ok:true, valid:true, user:{...} }   // 用户被封禁 / 应用被禁用时返回错误，请将用户踢下线

移动 App / 桌面软件无法安全保存 App Secret，使用 PKCE：客户端生成 code_verifier，服务端仅凭 code_verifier 即可换 token。

① 生成 code_verifier / code_challenge（S256）

async function pkcePair() {
  const verifier = crypto.randomUUID().replace(/-/g, '') + crypto.randomUUID().replace(/-/g, '');
  const d = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
  const challenge = btoa(String.fromCharCode(...new Uint8Array(d)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
  return { verifier, challenge };
}
const { verifier, challenge } = await pkcePair();

② 打开授权页（带 code_challenge + 可选 scope）

location.href = 'https://账号中心域名/oauth/authorize'
  + '?app_id=YOUR_APP_ID'
  + '&redirect_uri=' + encodeURIComponent('myapp://oauth/cb')   // 自定义协议回调
  + '&code_challenge=' + challenge + '&code_challenge_method=S256'
  + '&scope=login email'        // 可选：额外申请邮箱
  + '&state=' + state;

③ 回调拿到 code → 用 code_verifier 换 token（无需 app_secret）

fetch('https://账号中心域名/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ app_id: 'YOUR_APP_ID', code, code_verifier: verifier }),
})
  .then(r => r.json())
  .then(({ access_token, user }) => { /* 建立登录态 */ });

④ 按 scope 拉取字段

GET /api/oauth/userinfo   (Authorization: Bearer <access_token>)
→ scope=login 时： { uid, username, nickname, avatar }
→ scope=email 时：额外包含 email；scope=phone 时额外包含 phone

适合桌面软件 / 智能电视等无浏览器设备：桌面端展示二维码，用户用手机扫码在账号中心确认，桌面端轮询拿 code 完成登录。

① 桌面端：申请扫码会话

const { scan_id, qr_url } = await fetch('https://账号中心域名/api/oauth/qr/start', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ app_id: 'YOUR_APP_ID' }),
}).then(r => r.json());

② 把 qr_url 渲染成二维码给用户扫（任意二维码库）

// 例：qrcode 库（桌面/前端均可）
QRCode.toDataURL(qr_url).then(url => { qrImg.src = url; });
// 用户用手机扫二维码 → 打开 qr_url → 登录账号中心 → 点「确认登录」

③ 桌面端轮询结果（每 2s，最多 5 分钟）

let code = null;
for (let i = 0; i < 150 && !code; i++) {
  await new Promise(r => setTimeout(r, 2000));
  const s = await fetch('https://账号中心域名/api/oauth/qr/' + scan_id + '/status').then(r => r.json());
  if (s.status === 'confirmed') code = s.code;   // 一次性授权码，立即换 token
  if (s.status === 'expired') break;             // 超时/失效
}

④ 用 code 换 token

fetch('https://账号中心域名/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ app_id: 'YOUR_APP_ID', app_secret: 'YOUR_SECRET', code }),
}).then(r => r.json()).then(({ access_token }) => { /* 建立登录态 */ });

客户端类型	授权方式	状态
网站（Web）	授权码（重定向）+ scope	✅ 可用
移动 App / 桌面软件	PKCE 授权（免 secret）	✅ 可用
桌面 / 无浏览器设备	扫码登录（二维码确认）	✅ 可用
小程序	webview 授权 / openid 绑定	🚧 规划中（P5）

网站、App/桌面（PKCE）、桌面扫码三种接入方式均已上线，按上方标签页查看对应示例代码。

回调地址校验失败？ 确认 redirect_uri 与开放平台配置的回调地址完全一致（含协议/端口/路径），或命中回调域名白名单。

Secret 忘了？ 在应用详情「重新生成」，旧 Secret 立即失效。

用户被封禁/应用被禁用？ 调用 validate 会返回错误，你的站点应将该用户踢下线。

怎么让用户免登录？ 账号中心保持登录态，用户再次点登录会自动回跳，无需输密码。

常见错误码参考

error 字段（中文）	HTTP	出现场景 / 处理
应用不存在或未审核通过	400/404	App ID 错误，或应用仍在审核中 / 被禁用
回调地址不在白名单	400	redirect_uri 与申请时填写不一致，或域名未加入白名单
授权码无效或已过期	400	code 被重复使用 / 超过 10 分钟，重新走授权流程
授权码与应用不匹配	400	code 不是该 app_id 签发，检查 app_id 是否填对
app_secret 不正确	400	Secret 填错；PKCE 流程不要传 app_secret
code_verifier 校验失败	400	PKCE 的 verifier 与 authorize 时的 challenge 不匹配
token 无效或已过期	401	token 过期 / 已撤销，重新换取 token
用户不存在或被封禁	401/403	用户已注销或封禁，请将该用户踢下线
应用已停用 / 应用凭据不正确	401	应用被禁用，或 validate 时凭据错误
操作过于频繁，请稍后再试	429	触发限流，稍后重试
未登录	401	桌面扫码确认等需要登录的场景，引导用户先登录

所有接口错误统一返回 {"ok":false, "error":"中文描述", "code":HTTP状态码}，用 ok 字段判断成败即可。

安全建议

Secret 只存后端：App Secret 只允许出现在服务端，任何前端代码 / 客户端安装包一律禁止携带。
务必校验 state：authorize 带随机 state，回调时比对一致，防第三方伪造授权回跳。
token 存服务端：access_token 放在服务端会话，不要暴露给浏览器端 JS。
统一 HTTPS：回调地址与所有接口调用使用 HTTPS。
定期校验：每次用户访问调 /api/oauth/validate，token 失效或用户被封禁时立即踢下线。

欢迎使用 NaichaIDaaS（以下简称"本服务"）。本服务由 Naicha 开放平台运营。在使用本服务前，请您仔细阅读并充分理解本协议全部条款。您完成注册、登录或使用本服务，即视为您已阅读并同意受本协议约束。

服务内容：统一身份认证（IDaaS）、动态令牌（虚拟 MFA / TOTP）、扫码登录确认、账号资料管理、授权应用管理，及平台不时推出的其他功能与服务。
账号注册与使用：您应提供真实、准确、完整的注册信息；应对账号下的全部行为负责，妥善保管账号、密码及动态令牌密钥；账号仅限本人使用，不得转让、出借或出售。
用户行为规范：不得利用本服务从事违反法律法规、危害国家安全、损害公共利益或侵害他人权益的行为，不得破坏、干扰或攻击平台系统，不得利用漏洞谋取不正当利益。
授权登录与第三方应用：您授权第三方应用访问的信息以授权页面展示的范围为准，可随时在「授权管理」中查看并撤销；平台不对第三方应用的服务与质量负责。
个人信息保护：我们依法保护您的个人信息，具体处理规则详见《隐私保护指引》。
知识产权：本服务相关软件、技术、页面设计、文档等知识产权归平台所有，未经许可不得复制、修改或商用。
服务的变更与终止：平台可根据业务需要调整、暂停或终止部分或全部服务，并通过公告等方式提前告知；您也可依法注销账号终止服务。
免责声明：因不可抗力、网络故障、系统维护等原因导致服务中断或数据丢失的，平台在法律允许范围内不承担责任；因您未妥善保管账号、密码、动态令牌密钥导致的损失，由您自行承担。
违约责任：您违反本协议给平台或第三方造成损失的，应承担相应赔偿责任。
争议解决与法律适用：本协议适用中华人民共和国法律；因本协议产生的争议应友好协商，协商不成的向平台运营方所在地有管辖权的人民法院提起诉讼。
未成年人保护：未满 18 周岁的未成年人请在监护人陪同下阅读并在取得监护人同意后使用本服务。
协议更新：平台可能不时更新本协议，更新后将在本页面发布或公告提示，您继续使用即视为接受更新后的协议。

生效日期：2026 年 8 月 28 日

我们高度重视您的个人信息保护。本指引说明我们如何收集、使用、存储、共享与保护您的个人信息，以及您享有的权利。

我们收集的信息：注册与认证信息（用户名、昵称、邮箱、手机号、自愿提交的实名信息）；账号安全信息（登录日志：IP、设备、浏览器、时间，动态令牌绑定元数据）；授权信息及您主动提交的其他信息。
信息的使用：用于账号登录与身份认证、账号安全与风险控制、提供动态令牌与扫码登录等核心功能、按您的授权向第三方应用提供授权范围内的信息、履行法律义务。
信息的共享与公开：除取得您的明确授权或法律法规另有规定外，不向任何第三方共享您的个人信息，亦不出售；法定情形除外。
Cookie 与同类技术：仅使用必要的登录会话 Cookie 维持登录状态，不使用跟踪型 Cookie 用于广告。
信息的存储与保护：存储于中华人民共和国境内，期限为实现本指引目的所必需的期限；采用加密传输、密码不可逆加密存储、访问控制与安全审计等措施；动态令牌密钥仅存于您设备本地，服务器不保存明文。
您的权利：查阅与修改资料、查看并撤销应用授权、查看登录记录与已登录设备并可强制退出、导出个人数据、注销账号、就个人信息问题提出询问或投诉。
未成年人保护：若您为未成年人，请在监护人指导下使用并取得监护人同意；监护人发现未成年人未经同意提交个人信息，可联系我们删除。
指引更新：本指引可能适时更新，更新后在本页面发布并注明生效日期。