權限與同意

使用者在通行帳戶同意頁中看到的權限，取決於你在開發者入口網站中設定的必選 / 選用 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 並強制展示授權確認頁。新用戶端開發請以最新文件為準。

刪除識別碼或使用者撤銷同意後，請勿繼續使用舊權杖存取使用者資料。