開始使用

身份驗證

了解各 Kanorio API 接受的憑證類型、權限計算方式，以及如何安全地輪替與撤銷權杖。

每個 Kanorio API 均為不同呼叫者而設，並各自接受專屬憑證。請透過確認呼叫者身份來選擇合適的憑證。

權杖	前綴	身分	適用於	用途
個人存取權杖	`knr_pat_`	您本人，受限於您選擇的網站與權限	Management API, MCP	您的腳本、CLI、需要金鑰的編程輔助工具
服務帳戶權杖	`knr_sa_`	網站本身，非特定個人	Management API, MCP	CI、排程器以及在人員離職後仍需持續運行的合作夥伴後端
OAuth 存取權杖	`knr_at_`	您本人，透過您授權的應用程式	僅限 MCP	內建連接器的輔助工具，例如 Claude 或 ChatGPT
預覽權杖	`knr_pv_`	單一網站草稿的唯讀存取權	Content Delivery API	您自建前端的草稿模式
顧客權杖	`knr_cat_`	單一網站的單一登入顧客	Customer API, 受限的 Content Delivery API 讀取	您前端的登入、購買內容與訂單

Content Delivery API 對於已發佈的內容無需任何憑證。

Management API

在每次請求 https://app.kanorio.com/api/v1 時，請將權杖作為 Bearer 憑證發送。

curl https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer knr_pat_..."

個人存取權杖

請於帳戶設定 › API 存取中建立權杖。建立時您需要選擇：

網站。 指定網站，或包含您日後建立的所有網站。建立新網站需要「所有網站」權限。
權限。 選擇預設集（唯讀、編輯內容、完整存取）或個別權限。
過期時間。 權杖皆會過期。過期前您會收到電子郵件與收件匣通知。

權杖在網站上的有效權限，為該權杖允許範圍與您在該網站角色權限的交集。即使是完整存取權杖，亦無法編輯您僅具備檢視者角色的網站，且僅有網站擁有者可以取消發佈。

無論選擇何種預設集，某些權限永遠不會授權予權杖，包括發送或排程電子報、匯出資料、退款、刪除聯絡人，以及管理成員或帳務。代理人可以草擬電子報，但必須由人員從後台發送。

服務帳戶

服務帳戶屬於網站，而非個人。即使建立該帳戶的人員離開團隊，它仍能持續運作；撤銷服務帳戶將會同時撤銷其發出的所有權杖。

開啟網站設定 › 開發者並新增服務帳戶。您僅能授予您自身擁有的權限。
開啟該帳戶並發出權杖。請以其用途命名權杖，例如「GitHub Actions」。knr_sa_ 值僅會顯示一次。

服務帳戶僅能在其所屬網站內運作。帳戶層級的操作（例如建立網站或列出您所有的網站）會回傳 403 FORBIDDEN。在 OpenAPI 文件中的每個操作皆列出了其接受的呼叫者類型（於 x-kanorio-principals 欄位）；包含 SERVICE_ACCOUNT 的操作才接受服務帳戶權杖。

縮減服務帳戶的權限會立即縮減其現有權杖的權限。擴大權限則僅適用於後續發出的權杖。

範圍

Management API 參考中的每個操作皆顯示了其所需的權限。OpenAPI 文件中標註了相同的 x-kanorio-required-scope 值。若權杖缺少該範圍，將會收到 403 FORBIDDEN。請呼叫 GET /whoami 以查看目前權杖的權限。

MCP

MCP 伺服器位於 https://app.kanorio.com/api/mcp，它接受相同的個人存取權杖與服務帳戶權杖，以及 OAuth 2.1 存取權杖。具備內建連接器的助理會自動探索授權伺服器，並要求您在瀏覽器中核准存取。OAuth 存取權杖綁定於 MCP 伺服器，REST 端點將會拒絕此類權杖。請參閱 MCP。

Content Delivery API

已發佈的內容為公開且經過邊緣快取，因此瀏覽器可直接呼叫。

來自其他來源的瀏覽器呼叫，需將該來源加入網站設定 › 開發者下的 允許的來源。任何連接埠上的 localhost 與 127.0.0.1 永遠被允許。CORS 控制瀏覽器可讀取的內容。這並非授權邊界，且未經預覽權杖，草稿內容絕不會被提供。
草稿預覽。 在相同的設定頁面中，或使用 POST /sites/{id}/preview-tokens 建立 knr_pv_ 預覽權杖。請從您的伺服器以 X-Kanorio-Preview: knr_pv_... 標頭發送。預覽回應會繞過快取且不會被儲存。

Customer API

顧客無需密碼即可登入。網站擁有者可在 網站設定 › 顧客帳戶 中選擇啟用的方法；網站文件的 customerAccess.methods 會依顯示順序列出已啟用的方法。每種方法最終都會產生相同的 knr_cat_ 工作階段權杖。

電子郵件驗證碼 (email_code，預設開啟) 與 魔法連結 (email_link)：使用電子郵件地址呼叫 POST /api/v1/customer/auth/challenge 即可發送驗證碼。首先從 GET /api/v1/customer/auth/protection 取得機器人檢查：若使用內建檢查 (provider: "kanorio")，請使用 @kanorio/sdk 中的 solveProtectionChallenge 解決並將欄位隨請求發送；若使用擁有者的 Turnstile、reCAPTCHA 或 hCaptcha 金鑰，請使用 siteKey 與 action 渲染該小工具，並將其權杖作為 captchaToken 發送。接著使用 { "method": "code", "email", "code" } 或 { "method": "link", "token" } 呼叫 POST /api/v1/customer/auth/verify。
Google (google)：使用 { "method": "google", "baseUrl": <您的頁面來源> } 呼叫 POST /api/v1/customer/auth/oauth/start，將會回傳供應商 URL；請將瀏覽器重新導向至該處。Kanorio 會託管同意畫面，並將瀏覽器導回帶有 ?handoff= 的 baseUrl。請在 60 秒內進行交換：使用 { "method": "handoff", "token" } 呼叫 POST /api/v1/customer/auth/verify。若 Google 帳戶的電子郵件未經驗證，顧客將改為收到電子郵件驗證碼，並被導向至帶有 ?email=&verify=1 的頁面。
通行密鑰 (passkey)：呼叫 POST /api/v1/customer/auth/passkey/options，使用選項執行 navigator.credentials.get()，接著使用斷言與 challengeId 呼叫 POST /api/v1/customer/auth/passkey/verify。已登入的顧客可在 /api/v1/customer/passkeys 管理其通行密鑰。通行密鑰綁定於網站的主要網域，因此驗證程序必須在該來源上執行。

請在您的登入 UI 中處理來自 POST /api/v1/customer/auth/challenge 的這些回應：

代碼	處理方式
`429 RATE_LIMITED`	等待 `retryAfter` 秒後，讓顧客再次嘗試
`403 BOT_PROTECTION_FAILED`	取得新的挑戰（或重設小工具）並重新發送
`503 SERVICE_UNAVAILABLE`	登入功能暫時無法使用；顯示重試選項
`503 SHARED_SENDER_PAUSED`	此網站的電郵登入功能暫時暫停；請提供通行密鑰 (Passkeys) 或 Google 登入，或請顧客稍後再試

200 回應絕不會透露電子郵件是否已發送。Kanorio 會根據網站的登入流量調整機器人檢查：來自 /auth/protection 的挑戰可能會要求顯示小工具 (visible: true) 或更困難的內建謎題，因此請務必根據您取得的挑戰進行渲染，而非假設隱形流程。

在呼叫 Customer API 與受限的 Content Delivery API 讀取時，請將權杖作為 Authorization: Bearer knr_cat_... 發送。

顧客權杖僅代表該網站上的該名顧客。它無法讀取其他人的資料或呼叫 Management API。<kanorio-login> 元素會為您執行此流程。

輪替與撤銷

輪替：從個人存取權杖的選單中進行輪替。Kanorio 會發出一個具有相同設定的新權杖，並讓舊權杖在您選擇的寬限期內（無、一小時或一天）繼續運作。若懷疑權杖外洩，請選擇「無」。
撤銷：撤銷權杖以立即停止其運作。下一次使用該權杖的請求將會收到 401 UNAUTHORIZED。已完成的工作不會被復原。
使用任何權杖執行的活動，都會出現在網站的活動紀錄中，並歸類於該權杖擁有者或服務帳戶名稱下。

確保權杖安全

將權杖儲存在伺服器的環境變數或秘密管理服務中。切勿在權杖前加上 NEXT_PUBLIC_ 或將其封裝在流動裝置應用程式中。
切勿將權杖貼入 AI 對話中。真正的工具會從設定檔中讀取權杖。
每個工具使用一個權杖，每個整合使用一個服務帳戶，以便您能精確撤銷單一權杖。
給予每個權杖最窄的網站與權限範圍。