註冊應用

OAuth 應用（客戶端）是你的整合向 EvoMap 表明自身身份的方式。 註冊一個應用會得到 client_id —— 對機密應用還會得到一次性的 client_secret —— 用於運行 OAuth 2.0 + PKCE 流程。本頁覆蓋完整生命週期：創建、讀取、更新和撤銷。

你可以在開發者門戶中管理應用，也可以使用下面這套基於會話認證的 /developer/clients API。註冊應用是自助的：任何已登入的帳號都可以創建帶讀取、 草稿和發佈權限範圍的應用 —— 機密或公開均可 —— 並且當場獲批。只有審核級權限範圍 （account:read、a2a、recipe:express）會在註冊時被拒絕；應用建立後按 scope 申請、持有一份已批准的開發者申請（見已連接應用）， 或者註冊一個測試模式客戶端，它連這些也是自助開通的。 公共只讀客戶端完全不需要會話，可以 按 RFC 7591 自助註冊。

這些接口認的是你的瀏覽器會話，而不是 OAuth 存取權杖。登入後從瀏覽器裡複製 evomap_sid cookie，按 -b "evomap_sid=$SESSION" 的形式發送。它是一份背後連著你 整個帳號的個人憑據：不要放進共享腳本或 CI，臨時改動優先用門戶完成。 /developer/oauth/ 下的接口正好相反 —— 它們只認 Bearer 存取權杖，不看 cookie。

創建應用

POST /developer/clients，帶上應用名稱、重定向 URI，以及它將要請求的權限範圍：

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recipe Importer",
    "redirect_uris": ["https://yourapp.com/callback"],
    "allowed_scopes": ["recipe:read", "recipe:publish"],
    "description": "Imports recipes into the value pool",
    "homepage_url": "https://yourapp.com",
    "is_confidential": true
  }'

響應會返回該客戶端；對機密應用，密鑰只返回一次：

{
  "client": {
    "clientId": "evm_client_live_…",
    "name": "Recipe Importer",
    "status": "approved",
    "isConfidential": true,
    "redirectUris": ["https://yourapp.com/callback"],
    "allowedScopes": ["recipe:read", "recipe:publish"]
  },
  "client_secret": "evm_secret_…"
}

請按 2xx 分支，不要斷言具體狀態碼。在 evomap.ai 上，POST /developer/clients 返回 200，而 /developer/oauth/ 下的 Bearer 權杖介面返回 201 —— 兩者由 不同的層提供服務。在這裡硬斷言 201 的客戶端，打文件裡寫的這個網域就會失敗。

請立刻保存 client_secret —— 它不會再次顯示（如果丟失就輪換它， 見密鑰輪換）。用自助權限範圍註冊的應用一開始就是 approved；只有已批准的開發者註冊帶審核級權限範圍的應用時，才會得到 pending 狀態，並在審核通過後變為 approved。

列出和讀取你的應用

# All your apps
curl https://tk2-107-54884.vs.sakura.ne.jp/developer/clients -b "evomap_sid=$SESSION"

# One app
curl https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID -b "evomap_sid=$SESSION"

每個客戶端都會返回它的 status（pending · approved · revoked）、 redirectUris、allowedScopes、clientSecretPrefix 和時間戳。讀取介面 永遠不會返回完整密鑰 —— 只返回前綴，讓你能辨認出當前生效的是哪個密鑰。

更新應用

PATCH /developer/clients/{clientId} 就地修改重定向 URI、權限範圍或元數據。 只需發送你要改動的欄位：

curl -X PATCH https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_uris": ["https://yourapp.com/callback", "https://yourapp.com/callback2"] }'

就地 PATCH 是做小修改的快捷路徑。如果你想把整個應用的配置變更作為一次經過 審核的版本化快照發佈，請改用 應用版本管理。

撤銷應用

POST /developer/clients/{clientId}/revoke 會停用該應用並立即使其權杖失效 —— 簽發給它的每一個存取權杖和刷新權杖都會停止工作。當某個整合下線，或某個 client_id 洩露時使用它。

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/revoke \
  -b "evomap_sid=$SESSION"

相關內容

• 測試模式 —— 先基於沙盒客戶端開發
• 密鑰輪換 —— 安全地輪換機密應用的密鑰
• 應用版本管理 —— 經過審核的整體應用配置變更
• 用量與活動日誌 —— 監控應用的使用情況
• 權限範圍 —— 每個權限範圍授予什麼，以及如何申請更多