权限与同意

用户在通行账户同意页中看到的权限，取决于你在开发者门户中配置的必选 / 可选 scope、强制权限的理由与隐私政策，以及授权请求实际申请的 scope（服务端会按门户登记合并，见下文「旧客户端兼容」）。

2026-08-11 平台更新：权限可编辑、强制权限须填理由与隐私政策、每次登录须显式确认授权。详见同目录「更新」下的《2026-08-11权限与同意平台更新》。

兼容提示

• 已上线的旧客户端无需因本次平台更新而改代码或重新发布。 门户改权限、每次登录进入授权确认页，均由通行账户侧处理。
• 新接入或新开发的客户端请以本文档及同目录最新指南为准（按门户登记申请 scope、为强制权限准备理由与隐私政策链接，并按「每次都会出现授权确认页」设计登录 UX；不要依赖静默跳过授权页）。

开发原则

不能用单个 profile 一次拿走全部个人信息。基本资料按字段拆成多个 scope，用户可在同意页分别勾选或拒绝可选项。

• 授权请求若仍使用历史写法 scope=openid profile …，服务端会把 profile 展开为下列细项后再展示同意页。
• 令牌中的 scope 反映用户最终勾选的细项（以及 openid / email 等），而不再依赖整包 profile。
• UserInfo 对资料类声明保持稳定字段集合：已授权返回真实值（若用户未填写则为空字符串等）；未授权返回默认占位值，不会泄露真实资料。详见《令牌与用户信息》。

支持的 scope

历史别名（勿再作为「一揽子」权限依赖）：

开发者门户规则：

请按产品需要只勾选真正用到的项；不要把资料权限当成「一揽子必选」。强制索取权限时，理由应如实说明用途（例如：需要作为用户名在被授权方存储）。

成为开发者：通行账户须已绑定通知邮箱；否则无法登录开发者门户，也无法调用客户端注册 API。

同意页行为

1. 用户登录后每次进入同意 / 确认页（passport.swaymoon.com），不会因「此前已授权相同权限」而静默跳过。
2. 展示应用名称、图标（若有）；若配置了隐私政策链接，页面提供入口；用户点击跳转前会看到「该域不在摇月 Swaymoon 控制下…」提示。申请了强制权限时，隐私政策链接为必填。
3. 权限未变（相对该用户已有同意）：展示「确认登录」与已授权项目摘要，用户确认后继续。
4. 权限有增减：标题提示「权限已变更」，分区展示新增必需 / 新增可选（新增强制项旁显示开发者填写的理由）、不再申请、仍保留的授权；用户须对新增可选作出勾选，并确认后继续。确认后「不再申请」的权限不再写入同意记录。
5. 首次授权：按必需与可选分区列出；强制项旁显示理由。
6. 必选权限：勾选且不可取消；旁注为「必需」。
7. 可选权限：默认勾选，用户可逐项取消；旁注为「可选」。
8. 若本次将授予 email，而用户账户尚未绑定邮箱：须先完成邮箱绑定与验证，才能继续授权发码（必选 email 时会直接进入绑定页；可选时也可取消勾选邮箱后继续）。
9. 仅当本次申请包含 email，且用户账户已绑定通知邮箱时，邮箱权限旁出现下拉框（默认隐私邮件，可选真实邮箱）。第一方应用不提供该选项。
10. 「继续」后仅授予最终勾选的可选 scope 及全部必选 scope（不含「不再申请」项）。
11. 「取消」则授权不完成。

授权请求中的 prompt=consent 仍可发送，但不再是强制展示确认页的必要条件；生产环境也无需依赖该参数来「每次确认」。

旧客户端兼容

应用登录时会在地址里带上本次申请的权限（例如 scope=openid email）。有些已上线应用短期内改不了这串文字。

若你之后在门户把某权限改成必选，或新增了可选权限，通行账户会在服务端自动补全，旧应用不必立刻改代码：

• 必选：门户登记的全部必选都会进入本次授权（即使用户应用地址里没写）。
• 新增可选：用户已登录且尚未授权过该项时，确认页会列出供勾选；已授权过的不会再当「新增」。

举例：门户新增强制「用户名」、可选「头像」，旧应用仍只请求 openid email → 用户仍会看到「用户名」（必选），以及尚未授权过的「头像」（可选）。

更完整的说明与对照表见同目录「更新」下的《2026-08-11权限与同意平台更新》。

新客户端仍建议在授权请求中显式列出所需 scope，并与门户登记保持一致。

数据删除回调

注册或编辑应用时可配置 数据删除回调地址（规则与登记入口见同目录《注册与配置》「数据删除回调地址」）。当用户在隐私中心选择「撤销并请求删除数据」时，通行账户会：

1. 撤销对该应用的授权；
2. 向应用负责人通行账户绑定邮箱发送说明邮件（邮件会注明回调是否发送成功）；
3. 若已配置回调地址：由通行账户服务端向该地址 POST JSON（type=swaymoon.passport.data_deletion_request），请求头含 X-Swaymoon-Signature: sha256=<hmac> 与 X-Swaymoon-Request-Id。签名对原始请求体字节做 HMAC-SHA256（勿先 JSON 解析再序列化后验签）。

签名密钥（明文）

请妥善保存上述明文。通行账户侧会把同一份明文存为 webhook 签名密钥；库内用于 OAuth 客户端认证的 client_secret 可能随后被编码为 bcrypt 等不可逆哈希，不能用哈希或带 {bcrypt} 前缀的存储值做 HMAC。轮换密钥后，请改用新下发的明文验签。

回调地址仅允许 HTTPS，且主机不能是 127.0.0.1 / localhost。登录 Redirect 仍可用 loopback（浏览器跳转）；删除回调是服务端出站，本地联调请用 HTTPS 隧道。点删除时接收端须已在运行。

请及时按 subject（及你方保存的用户标识）删除本地数据。可运行联调见《Python 最小可运行示例》机密客户端一节的「演示数据删除回调」。

因此，authorize 中列出的可选 scope 不一定全部出现在令牌的 scope 中。换取令牌后请读取响应中的 scope，并据此解释 UserInfo（未授权字段为默认值，而非真实数据）。

请求与配置的关系

• 授权请求中的 scope 应当是客户端已登记权限范围的子集（登记时若带有 profile，服务端会视同已登记对应细项）；服务端还会按上文「旧客户端兼容」并入门户必选与新增可选。
• 授权请求必须包含 openid。
• 推荐直接申请细项，例如：scope=openid name picture；也可暂时继续传 profile，由服务端展开。
• 用户同意后会写入同意账本；可在通行账户「隐私」页查看，见用户指南《授权应用》。

产品侧与邮箱

• 不需要邮箱就不要申请 email。
• 需要邮箱用于注册/建档时，申请 email 即可：未绑定邮箱的用户会在授权流程中完成绑定；授权成功后 UserInfo 返回可用的 email。
• 用户可能选择隐私邮箱：你方仍只收到一个可发信的地址，真实邮箱不会提供给你方；按普通邮箱处理即可。
• 以 sub 作为账号主键，邮箱作联系方式或本地账号名。

变更权限

如需增加或减少 scope：

1. 在开发者门户打开标识符，编辑对应应用，在向导「功能」步调整可选 / 必选权限并保存（无需因改权限而重新创建客户端；客户端类型仍不可互转）。
2. 将某权限设为必选时：为该权限填写对用户可见的理由，并确保已配置隐私政策链接。
3. 用户下次登录同一应用时会进入授权页：若权限有增减，将看到新增 / 不再申请 / 仍保留的分区，并对新增可选作出选择；若权限未变，则确认登录即可。

已上线的旧客户端无需为配合本次能力而改代码；门户保存后，由服务端合并 scope 并强制展示授权确认页。新客户端开发请以最新文档为准。

删除标识符或用户撤销同意后，请勿继续使用旧令牌访问用户数据。