註冊與設定 開發人員
上次更新：2026年8月16日
註冊與設定
接入前，請先在開發者入口網站建立 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 |
| JWT 斷言用戶端 | private_key_jwt | private_key_jwt | 伺服器保管 EC P-256 私鑰，入口只登記公鑰；換權杖時用 client_assertion |
三種均強制 PKCE（S256），並要求使用者在授權頁明確確認後登入（不會因「此前已授權」而靜默略過）。用戶端類型在建立後不可互轉。
JWT 斷言是什麼
private_key_jwt 是 OAuth 2.0 / OpenID Connect 的一種用戶端認證方式（RFC 7523）：換權杖時，你的伺服器用自己保管的私鑰簽發一枚短期 JWT（client_assertion），通行帳戶用你在入口登記的公鑰驗簽。它仍是機密用戶端——私鑰不能離開伺服器——只是證明身分的材料從「雙方共享的 client_secret」換成了「非對稱金鑰」。
| 對比 | 機密（client_secret_basic） | JWT 斷言（private_key_jwt） | 非機密（none） |
|---|---|---|---|
| 適合 | 有後端、可保管共享金鑰 | 有後端、希望入口看不到私鑰、要按 kid 輪換 | SPA / 靜態站 / 原生，執行時期不能藏金鑰 |
| 入口保存 | 不回看 client_secret 明文 | 只存公鑰 | 無金鑰 |
| 換權杖 | HTTP Basic + PKCE | client_assertion + PKCE | 表單 client_id + PKCE |
| Refresh Token | 有 | 有 | 無 |
選 JWT 斷言：伺服器端應用程式，不想把長期 client_secret 放在環境變數裡，或需要不停機輪換金鑰。
不要選：純瀏覽器 SPA、無法保管私鑰的靜態站——繼續用非機密。
換權杖時 client_assertion 必須帶哪些聲明、請求長什麼樣，見《授權碼與 PKCE》與《範例與疑難排解》。
精靈欄位
| 步驟 | 欄位 | 說明 |
|---|---|---|
| 描述 | 描述、用戶端類型、公鑰 JWK | 「描述」即應用程式名稱，展示在使用者同意頁；類型見上表（編輯時類型唯讀）。選 JWT 斷言時須貼上 EC P-256 公鑰 JWK（含 kid） |
| 圖示 | 預設圖示或上傳裁剪 | 同意頁展示；預設可依應用程式首字產生；也可上傳 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 接入非機密用戶端》
JWT 斷言用戶端
| 欄位 | 說明 |
|---|---|
client_id | 以 swm_ 開頭的用戶端識別 |
client_secret | 不發放 |
公鑰 kid | 建立時登記的 EC P-256 公鑰識別；可在詳情頁追加更多公鑰以便輪換 |
設定要點：
- 認證方式：
private_key_jwt（client_assertion+ ES256） - 授權類型：
authorization_code、refresh_token - Access Token 約 5 分鐘；Refresh Token 約 180 天
- 換取權杖時提交
client_id、code_verifier與client_assertion（不要使用 HTTP Basic） - 私鑰只留在你的伺服器；入口拒絕接受私鑰 JWK
重新導向 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 明文；非機密 / JWT（已配回呼）：建立或輪換時下發的 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、用戶端類型與認證方式、必選 / 選用權限。 - 詳情：檢視回呼、隱私權政策、權限、webhook 金鑰是否已簽發，以及 JWT 公鑰
kid。 - 編輯：可修改描述（名稱）、圖示、重新導向 URI、資料刪除回呼位址、隱私權政策連結、必選 / 選用權限與強制權限理由。
- 輪換金鑰：機密用戶端可在詳情頁輪換
client_secret（同時更新刪除回呼驗簽明文）。非機密 / JWT 可簽發或輪換webhookSecret。 - 追加公鑰：JWT 斷言用戶端可在詳情頁追加另一把公鑰（按
kid區分），便於不停機輪換。 - 不可編輯：用戶端類型（機密 / 非機密 / JWT 斷言）建立後鎖定。若需更換用戶端類型，請刪除舊識別碼並重新註冊，再更新應用程式內設定。
- 刪除：刪除識別碼後，已發放的權杖將無法繼續用於該用戶端，使用者側的授權關係也會失效。
相容提示：已上線的舊用戶端無需因平台支援「可編輯權限 / 強制授權確認」而改程式碼；新用戶端開發請以最新文件為準。詳見《權限與同意》。
建立用戶端可呼叫 POST /api/v1/developer/clients，在 JSON 體中傳入 clientType、requiredScopes / optionalScopes、scopeReasons，以及選用的 dataDeletionUri、privacyPolicyUri。更新已有用戶端可呼叫 PUT /api/v1/developer/clients/{clientId}（可更新權限與理由）。
下一步：閱讀同目錄《接入概述》，再實作《授權碼與 PKCE》。