注册与配置 开发人员
上次更新：2026年8月12日
注册与配置
接入前，请先在开发者门户创建 OAuth / OIDC 客户端（页面称为标识符），配置重定向 URI 与权限，并按客户端类型取得凭证。协议接入（授权码、令牌、同意页等）见本目录下《接入概述》及后续文档。
2026-08-11：标识符权限可在门户编辑；强制权限须填理由与隐私政策；用户每次登录须确认授权。变更说明见同目录「更新」下的《2026-08-11权限与同意平台更新》。
入口
- 使用通行账户登录 develop.swaymoon.com。
- 在首页「计划资源」中进入标识符（侧栏亦有同名入口）。
- 点击左上角 +，打开「注册应用标识符」向导。
- 按照向导依次完成：描述 → 图标 → 重定向 URI → 功能 → 确认。
开发者门户通过通行账户 API（https://api-passport.swaymoon.com/api/v1/developer/...）管理客户端。执行相关操作前，你需要先登录通行账户。
客户端类型
| 类型 | clientType | 认证方式 | 适用场景 |
|---|---|---|---|
| 机密客户端 | confidential（默认） | client_secret_basic | 可由后端安全保管 client_secret 的 Web / 服务端应用 |
| 非机密客户端 | public | none（仅 PKCE） | 纯 HTML / 静态站 / 纯 SPA、原生客户端等：运行时不宜保管 client_secret |
两者均强制 PKCE（S256），并要求用户在授权页显式确认后登录（不会因「此前已授权」而静默跳过）。客户端类型在创建后不可互转。
向导字段
| 步骤 | 字段 | 说明 |
|---|---|---|
| 描述 | 描述、客户端类型 | 「描述」即应用名称，展示在用户同意页；类型见上表（编辑时类型只读） |
| 图标 | 默认图标或上传裁剪 | 同意页展示；默认可按应用首字生成；也可上传 JPEG / PNG / WebP，裁剪为约 512×512 正方形 JPEG（不超过 512KB） |
| 重定向 URI | Redirect URI 白名单 | 授权成功或取消后，用户浏览器返回的地址；至少配置一条，且须与授权请求中的 redirect_uri 完全一致（可添加多条）。本地可用 http://127.0.0.1 |
| 重定向 URI | 数据删除回调地址（可选） | 用户请求删除数据时，由通行账户服务端 POST 签名请求包的地址（不是浏览器跳转）。见下文「数据删除回调地址」 |
| 重定向 URI | 隐私政策链接 | 用户在同意页与「应用授权」详情中可见；点击前会提示该域不在摇月控制下。申请任一强制权限（除 openid 外的必选）时必填。见下文「隐私政策链接」 |
| 功能 | 必选 / 可选 scope 与理由 | 新建与编辑均可配置；openid 始终必选；email 与资料细项可设为必选、可选或不申请。设为必选时须填写对用户可见的理由，并配置隐私政策。详见《权限与同意》 |
| 确认 | — | 新建点「注册」；编辑点「保存」可更新名称 / 图标 / 回调 / 数据删除地址 / 隐私政策 / 权限与理由 |
创建结果
机密客户端
| 字段 | 说明 |
|---|---|
client_id | 以 swm_ 开头的客户端标识，可以公开出现在授权 URL 中 |
client_secret | 仅在创建时展示一次，请立即将其存入密钥管理系统；如有遗失，需删除标识符并重新创建 |
配置要点：
- 认证方式：
client_secret_basic - 授权类型：
authorization_code、refresh_token - Access Token 约 5 分钟；Refresh Token 约 180 天（刷新后不再重复使用旧的 Refresh Token）
非机密客户端
| 字段 | 说明 |
|---|---|
client_id | 以 swm_ 开头的客户端标识 |
client_secret | 不发放 |
配置要点：
- 认证方式：
none - 授权类型：仅
authorization_code（不签发refresh_token；Access Token 过期后重新走授权码流程） - Access Token 约 5 分钟
- 换取令牌时在请求体提交
client_id与code_verifier，不要使用 HTTP Basic - 可运行联调见《Python 最小可运行示例》；AI 辅助见《使用生成式 AI 接入机密客户端》《使用生成式 AI 接入非机密客户端》
重定向 URI（Redirect URI）规则
- 必须提供至少一条非空 URI。
- 授权请求中的
redirect_uri必须与登记值逐字符一致，包括 scheme、host、port、path 和 query。 - 不要在 Redirect URI 中使用
#fragment（协议不允许）。 - 生产环境强烈建议使用
https://。本地开发可以使用http://127.0.0.1:...等环回地址，但须符合服务器的校验策略。 - 不支持通配符域名。对于多个环境，请分别登记对应的 URI。
http://127.0.0.1与http://localhost视为不同地址。- 谁在访问：授权完成后由用户浏览器跳转到该地址。因此登记
http://127.0.0.1:8766/callback时，只要浏览器与本地 demo 在同一台电脑上，登录回调即可到达。
数据删除回调地址
可选。用户在通行账户隐私中心选择「撤销并请求删除数据」时，通行账户会：
- 撤销对该应用的授权；
- 向应用负责人绑定邮箱发送说明邮件；
- 若已配置本地址，由通行账户 API 进程所在机器向该 URL 发起
POST（签名约定见《权限与同意》）。
| 项 | 说明 |
|---|---|
| 是否必填 | 否；未配置则只发邮件、不发 HTTP 回调 |
| 允许的 URL | 仅可被通行账户服务端访问的 https://… |
| 禁止 | http://（任意）、127.0.0.1、localhost、::1 等回环地址 |
| 谁在访问 | Passport 服务端，不是浏览器（因此不能照搬登录用的 loopback Redirect） |
| 本地联调 | 使用 ngrok、Cloudflare Tunnel 等把本机接收端暴露为 HTTPS，把隧道 URL 登记于此；点删除时隧道与接收端须已在运行 |
| 与 Redirect | 登录 Redirect 仍可用 http://127.0.0.1（浏览器跳转）；删除回调与登录回调不是同一条通路 |
| 签名密钥 | 机密：创建时下发的 client_secret 明文；非机密（已配回调）：创建时下发的 webhookSecret。须对原始 body 验签，见《权限与同意》 |
可运行联调见《Python 最小可运行示例》机密客户端一节的「演示数据删除回调」。
隐私政策链接
可选。登记后，用户可在：
- 授权同意页（若已配置）；
- 通行账户 隐私 → 应用授权 → 应用详情；
查看并打开该链接。点击跳转前，通行账户会提示：该域不在摇月 Swaymoon 控制下，其内容不受摇月 Swaymoon 管理。
| 项 | 说明 |
|---|---|
| 是否必填 | 申请除 openid 外的强制权限时必填；否则可选 |
| 允许的 URL | 公网 https://…；本地联调可用 http://127.0.0.1 / http://localhost（亦可用 https://） |
| 禁止 | 非回环主机的 http:// |
| 谁在访问 | 用户浏览器（与登录 Redirect 相同，不是服务端出站） |
| API 字段 | 创建 / 更新客户端请求体中的 privacyPolicyUri |
建议在应用正式上线前配置可公开访问的 HTTPS 隐私政策页，便于用户在授权前了解你方如何处理其数据。
权限配置建议
| 需求 | 建议 scope |
|---|---|
| 仅登录、建立本地账号 | openid |
| 需要展示用户称呼 | openid + name（必要时再加 nickname / picture；可设可选或必选） |
| 需要联系邮箱 | openid + email（可在门户设为必选或可选；可选时尊重用户取消） |
| 需要在本应用存储用户名 | openid + preferred_username（若设为必选，须填写理由与隐私政策） |
openid 始终为必选。将 email 或资料细项设为必选时，须填写对用户可见的理由，并配置隐私政策链接。可选权限在同意页默认勾选，用户可以取消，详见《权限与同意》。
管理操作
- 列表：查看已创建的标识符、名称、
client_id、客户端类型与认证方式、必选 / 可选权限。 - 编辑：可修改描述（名称）、图标、重定向 URI、数据删除回调地址、隐私政策链接、必选 / 可选权限与强制权限理由。
- 不可编辑：客户端类型（机密 / 非机密）创建后锁定。若需更换客户端类型，请删除旧标识符并重新注册，再更新应用内的
client_id/client_secret配置。 - 删除：删除标识符后，已发放的令牌将无法继续用于该客户端，用户侧的授权关系也会失效。
兼容提示：已上线的旧客户端无需因平台支持「可编辑权限 / 强制授权确认」而改代码；新客户端开发请以最新文档为准。详见《权限与同意》。
创建客户端可调用 POST /api/v1/developer/clients，在 JSON 体中传入 clientType、requiredScopes / optionalScopes、scopeReasons，以及可选的 dataDeletionUri、privacyPolicyUri。更新已有客户端可调用 PUT /api/v1/developer/clients/{clientId}（可更新权限与理由）。
下一步：阅读同目录《接入概述》，再实现《授权码与 PKCE》。