身分驗證與權限範圍
每次調用 Kaleidr 平台 API 都必須攜帶一種憑證。憑證分為三種，API 對它們的處理方式各不相同：
- 可公開使用的金鑰用於在瀏覽器中標識您的組織。它不能直接調用 API，必須先交換為工作階段。
- 工作階段權杖是瀏覽器實際調用 API 時使用的憑證。它有效期限較短，並綁定到一個網站來源和一種產品。
- 伺服器金鑰是由您的後端在每次要求中直接發送的機密憑證。
本文介紹每種憑證的發送方式、工作階段交換過程、各個權限範圍開放的功能、vendor 權限範圍的授予方法，以及每種身分驗證錯誤的原因和解決辦法。如果您想瞭解憑證洩露後可能帶來的影響，請參閱安全模型。
憑證類型
| 憑證 | 前綴 | 存放位置 | 使用方式 | 方案 |
|---|---|---|---|---|
| 可公開使用的金鑰 | kld_pk_live_… | 頁面原始碼 | 向工作階段交換接口發送一次；其他所有端點均拒絕該金鑰 | Free、Pro、Enterprise |
| 工作階段權杖 | kld_sess_live_… | 瀏覽器內存 | 從頒發權杖的頁面發起每次運行時調用時發送 | 由可公開使用的金鑰或已發佈地圖生成 |
| 伺服器金鑰 | kld_sk_live_… | 僅存放在您的後端 | 每次運行時調用均發送；如果要求攜帶 Origin 標頭，則會被拒絕 | Pro、Enterprise |
| 舊版金鑰 | kld_live_… | 您的後端 | 與伺服器金鑰一樣，可直接作為憑證使用。輪替後會生成伺服器金鑰 | 僅限現有金鑰 |
使用金鑰管理 API 並設定 environment: "test" 創建的金鑰，會以 test 代替 live（kld_pk_test_…、kld_sk_test_…）。測試金鑰無法載入底圖圖磚。
金鑰僅在創建或輪替時完整顯示一次。Kaleidr 只存儲雜湊值，因此無法恢復丟失的金鑰；請輪替金鑰。
傳送憑證
可以透過任意一個標頭髮送憑證。所有端點均接受這兩種標頭。
Authorization: Bearer kld_sk_live_…
X-Api-Key: kld_sk_live_…
如果要求同時攜帶兩者，且 Authorization 的值以 Kaleidr 前綴開頭， 則優先使用它；否則讀取 X-Api-Key。切勿把伺服器金鑰放入 URL。
各類憑證在運行時端點（工作階段交換端點除外）上的行為如下：
| 憑證 | 運行時端點的處理結果 |
|---|---|
| 可公開使用的金鑰 | 401 publishable_requires_session。必須先交換為工作階段。 |
沒有 Origin 標頭的伺服器金鑰 | 接受金鑰，然後檢查 IP 允許清單、權限範圍、允許的產品、額度和速率限制。 |
帶有 Origin 標頭的伺服器金鑰 | 403 server_key_in_browser。瀏覽器在跨網站要求時會添加 Origin，API 因而能夠識別網頁中使用的伺服器金鑰。 |
| 來自權杖頒發來源的工作階段權杖 | 接受。 |
帶有不同 Origin 的工作階段權杖 | 403 session_origin_mismatch。 |
不帶 Origin 的已發佈地圖工作階段權杖 | 403 session_origin_mismatch。 |
JavaScript SDK 會更早實施同一規則：Kaleidr.mount 在瀏覽器中發現 kld_sk_… 金鑰時，不會發起要求，而是直接拒絕。
工作階段交換
可公開使用的金鑰需要透過一個端點換取工作階段權杖。SDK 在每次使用金鑰掛載元件時自動完成交換，並負責刷新權杖。只有在自行構建瀏覽器使用者端時，您才需要直接調用此端點。
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
X-Api-Key: kld_pk_live_…
Content-Type: application/json
{ "product": "chat" }
必須提供 product，其值只能是 chat、editor、viewer 或 tile。要求必須帶有 Origin 標頭；瀏覽器會自動添加。
{
"session_token": "kld_sess_live_eyJhbGciOi…",
"expires_in": 900,
"product": "chat",
"basemap_style_id": null
}
| 欄位 | 含義 |
|---|---|
session_token | 運行時調用使用的憑證，格式為 kld_sess_{env}_{token}。 |
expires_in | 有效期限，單位為秒。透過金鑰生成的工作階段有效期限為 900 秒。請讀取該欄位，不要在代碼中寫死數值。 |
product | 工作階段綁定的產品。 |
basemap_style_id | 組織的預設底圖；未設定時為 null。 |
工作階段的綁定條件
- 一個來源。 即交換要求的
Origin。來自其他來源的調用會被拒絕。 - 一種產品。
tile工作階段不能調用聊天端點。 - 受限的權限範圍集合。 工作階段僅包含產品所需的權限範圍：聊天使用
ai，編輯器使用design，圖磚使用maps，查看器不需要權限範圍。只有當金鑰具有vendor且方案允許（Enterprise）時，聊天工作階段才會保留vendor。任何其他產品的工作階段都不會包含這一權限範圍。
更新
使用者端無法要求更長的有效期限。應在 expires_in 到期前重新交換。SDK 會在到期前 90 秒刷新；當後台標籤頁重新變為可見，且工作階段距離到期不足 90 秒或已經到期時，也會刷新；刷新失敗後則每隔 30 秒重試。如果首次交換失敗，元件掛載就會失敗，且不會自動重試。
每次為 product: "tile" 交換工作階段，都會消耗組織額度中的一次地圖載入；其他產品交換工作階段不收費。工作階段交換具有單獨的每金鑰速率限制，與運行時調用分開計算。請參閱額度與速率限制。
檢查順序
工作階段交換在遇到第一項失敗的檢查時立即停止：
| 順序 | 檢查項目 | 失敗結果 |
|---|---|---|
| 1 | 金鑰有效 | 401 Invalid or missing API key |
| 2 | 金鑰的工作階段交換速率限制 | 429 rate_limited |
| 3 | 金鑰是可公開使用的金鑰 | 403 publishable_key_required |
| 4 | 要求包含 Origin 標頭 | 403 origin_required |
| 5 | 如果金鑰設定了允許來源清單，要求來源必須在其中 | 403 origin_not_allowed |
| 6 | 金鑰的產品限制沒有排除該產品 | 403 product_not_allowed |
| 7 | 當前方案包含該產品 | 403 tier_capability_not_allowed |
| 8 | 金鑰具有產品所需的權限範圍 | 403 insufficient_scope；如果金鑰具備該權限範圍，但當前方案不再支持，則為 tier_capability_not_allowed |
| 9 | 對於 tile：仍有可用地圖載入次數 | 429 map_load_quota_exceeded |
在終端機中測試
curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
-H "X-Api-Key: kld_pk_live_…" \
-H "Origin: https://www.example.com" \
-H "Content-Type: application/json" \
-d '{"product":"chat"}'
這種測試之所以有效，是因為 Origin 是普通 HTTP 標頭，任何非瀏覽器使用者端都可以自行設定。因此，允許來源清單屬於瀏覽器控制機制，並非保密手段。請參閱 CORS 與允許的來源。
已發布地圖的工作階段
如果從 Studio 發佈的地圖在其 Kaleidr AI 圖塊中開啓了 Control Tower 或 Popup Window，訪客無需在網頁中使用金鑰即可聊天。網頁改為使用地圖的公開 ID 以及要開啓的功能交換工作階段：
POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions
Content-Type: application/json
{ "share_id": "your-map-id", "feature": "control_tower" }
{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }
這種工作階段僅適用於聊天，包含 ai 權限範圍，有效期限為 300 秒，費用計入地圖所有者的組織。它永遠不包含 vendor。工作階段只能在發起交換的網頁使用；如果調用缺少 Origin 或來源不同，將被拒絕。拒絕原因如下：
| 狀態碼 | 錯誤代碼 | 原因 |
|---|---|---|
| 403 | origin_required | 要求缺少 Origin 標頭。 |
| 404 | not_found | 不存在使用此 ID 的已發佈地圖或分享連結，或分享連結的地圖已取消發佈。 |
| 403 | chat_disabled | 地圖的 Kaleidr AI 未開啓所請求的功能。 |
| 403 | origin_not_allowed | 網頁不在地圖允許的域名清單中。 |
| 403 | owner_has_no_organization | 地圖所有者沒有可計費的組織。 |
| 403 | tier_capability_not_allowed | 地圖所有者的方案不包含聊天功能。 |
| 429 | rate_limited | 此地圖或此地址發起的工作階段交換過多。 |
配置方法請參閱已發佈地圖上的 Kaleidr AI。
權限範圍
每個金鑰都有權限範圍。每個端點系列都需要對應的權限範圍。
| 權限範圍 | 開放的功能 | 適用對象 |
|---|---|---|
ai | /chat/* 和 /retrieval/* 端點 | Chat，以及調用聊天或查詢端點的任何後端 |
design | /design/* 端點 | Editor 工作階段，以及調 用設計端點的任何後端 |
maps | 底圖工作階段 | Tile |
vendor | 本身不開放端點，但允許聊天回答使用組織自行發佈的數據。 | 已上傳數據時的 Chat |
除非另有指定，新金鑰預設具有 ai、maps 和 design。在 Free 方案下，金鑰始終具有 Free 的全部能力：恰好這三個權限範圍以及全部四種產品（chat、editor、viewer、tile），無論要求指定哪一種產品。vendor 從不預設授予，只有 Enterprise 組織可以創建包含它的金鑰。
如果創建金鑰時指定的權限範圍或產品超出方案支持範圍，要求會收到 403 tier_capability_not_allowed。系統不會不報錯就悄悄移除要求中的內容。典型情況是在 Free 或 Pro 中要求 vendor。
權限範圍在創建金鑰時就已固定。 此後任何端點或設定都無法更改。輪替金鑰會繼承原有權限範圍，但會去除當前方案已不支持的部分。若需更改權限範圍，請創建新金鑰並撤銷舊金鑰。
Free 方案的金鑰輪替遵循 Free 規則。 在 Free 下，輪替後生成的可公開使用的金鑰具有 Free 的全部能力（ai、maps、design 及全部四種產品），不受舊金鑰權限範圍影響。Free 不允許輪替伺服器金鑰或舊版金鑰：要求會被拒絕，並回傳 403 free_plan_publishable_only。
金鑰實際權限取決於金鑰與方案兩者中更嚴格的一方
每個要求都會對照您組織當前方案的功能範圍，檢查金鑰中保存的權限範圍和產品設定。更改方案不會直接修改金鑰，但會改變金鑰能夠執行的操作：
insufficient_scope：金鑰從未獲得相應權限範圍。解決方法：換用具有該權限範圍的金鑰。tier_capability_not_allowed：金鑰具備相應權限範圍，但當前方案不支持。解決方法：更改方案。
vendor 是第二種情況的例外，因為它不開放任何端點。當低於 Enterprise 的方案中仍保存著具有 vendor 的金鑰時，系統不會拒絕要求：要求可以成功，但生成的回答不會使用您組織的數據。
如果金鑰的產品清單為空，則可訪問當前方案包含的所有產品。沒有任何權限範圍的金鑰在所有端點都會被拒絕。
產品限制適用於所有金鑰
allowed_products 可以將金鑰限制為 chat、editor、viewer 和 tile 中的部分產品。所有金鑰類型都會在使用時執行這一限制：
| 金鑰 | 檢查限制的時機 | 拒絕結果 |
|---|---|---|
| 可公開使用的金鑰 | 工作階段交換時，檢查要求的 product | 403 product_not_allowed |
| 伺服器金鑰或舊版金鑰 | 每次運行時要求，檢查端點所屬產品 | 403 product_not_allowed |
每個端點系列都歸屬於其所需權限範圍對應的產品：
| 端點 | 權限範圍 | 受限金鑰必須允許的產品 |
|---|---|---|
/chat/*、/retrieval/* | ai | chat |
/design/* | design | editor |
因此，即便伺服器金鑰具有 ai 權限範圍，如果創建時指定了 "allowed_products": ["tile"]，調用 /chat/control/stream 仍會被拒絕並回傳 403 product_not_allowed。如果伺服器金鑰僅允許 viewer，則無法調用任何運行時端點，因為已發佈地圖不需要金鑰。如果希望金鑰可以訪問其權限範圍允許的所有端點，請將該清單留空。
此處不會再次檢查工作階段權杖，因為交換時它已經綁定到單一產品。
| Free | Pro | Enterprise | |
|---|---|---|---|
| 可公開使用的金鑰 | 是 | 是 | 是 |
| 伺服器金鑰 | 否 | 是 | 是 |
ai、maps、design | 是 | 是 | 是 |
vendor | 否 | 否 | 是 |
與 Free 相比，Pro 增加了伺服器金鑰功能，並提高了活躍金鑰數量上限。完整方案對照表請參閱獲取 API 金鑰。
vendor 權限範圍
vendor 本身不開放任何端點。它決定使用此金鑰生成的聊天回答能否在 Kaleidr 通用知識之外，使用您組織自己發佈的數據。從上傳到生成回答的完整流程，請參閱您的數據：概覽。
哪些組織可以使用：
- Free 和 Pro 不能持有
vendor。無論是否提交vendor_acknowledged，申請創建包含該權限範圍的金鑰都會收到 403tier_capability_not_allowed，並且不會創建金鑰。 - Enterprise 可以創建具有
vendor的金鑰。
此權限範圍負責透過金鑰讀取數據。上傳數據屬於另一項單獨權限，授予組織所有者或管理員，而不是任何金鑰；該權限同樣僅向 Enterprise 開放，Free 和 Pro 無法上傳業務數據。已登錄使用者在 Kaleidr Studio 中添加到地圖的文件屬於另一項功能，所有方案均可使用，且無法透過任何權限範圍讀取：請參閱地圖上的數據集。
API Keys 頁面無法授予 vendor。請透過金鑰管理 API 創建包含該權限範圍的金鑰：
curl -s https://api.kaleidr.com/shared-api/api-keys \
-H "Authorization: Bearer $KALEIDR_ACCOUNT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "store-locator-chat",
"key_type": "publishable",
"scopes": ["ai", "vendor"],
"vendor_acknowledged": true,
"allowed_origins": ["https://www.example.com"]
}'
如果可公開使用的金鑰包含 vendor，就必須提供 vendor_acknowledged: true。否則要求會回傳 422 vendor_scope_requires_acknowledgement。這是因為可公開使用的金鑰存在於公開的頁面原始碼中；任何訪問該網頁的人都能讀取此金鑰可訪問的數據。伺服器金鑰無需提供此確認。
在為可公開使用的金鑰添加 vendor 之前：
- 每個網站使用一把獨立金鑰。只有確實需要使用您數據生成回答的網站，才應授予
vendor。 - 將已發佈數據視為該網站上的公開信息。不要發佈成本價格、尚未公佈的費率或任何不願展示在網頁上的內容。
- 請注意，已經發放的工作階段不會自動獲得該權限範圍。創建帶有
vendor的金鑰後，只有之後交換生成的工作階段才會獲得它。
要撤回 vendor，請撤銷原 金鑰並創建不帶該權限範圍的替代金鑰。撤銷會從下一次要求起生效，包括已經發放的工作階段。
當組織不再使用 Enterprise 方案時
從 Enterprise 降級為 Pro 或 Free，不會修改已有金鑰，也不會使其全部失效：
| 項目 | 降級後的情況 |
|---|---|
具有 vendor 的金鑰 | 其他功能仍可正常使用，但聊天回答不再使用您的數據。不會透過錯誤、狀態或欄位提示這一變化。 |
| 降級前發放的瀏覽器工作階段 | 工作階段被終止。下一次要求回傳 401，SDK 隨後獲取不帶 vendor 的新工作階段。 |
輪替包含 vendor 的金鑰 | 在 Pro 中：回傳 201 表示成功。替代金鑰繼承相同權限範圍，但不包含 vendor；產品清單保持不變。在 Free 中：可公開使用的金鑰的替代金鑰包含 ai、maps、design 和全部四種產品，不受舊金鑰設定影響；伺服器金鑰和舊版金鑰的輪替會被拒絕，回傳 403 free_plan_publishable_only。 |
創建包含 vendor 的金鑰 | 回傳 403 tier_capability_not_allowed，要求被拒絕。 |
| 您的發佈版本 | 在任何方案下，所有者和管理員仍可透過上傳 API 列出、取消發佈和刪除版本。Free 和 Pro 的上傳及發佈要求會被拒絕，回傳 403 vendor_data_not_on_plan。 |
如果組織重新升級至 Enterprise，仍然保存有 vendor 的金鑰可以再次訪問數據。若金鑰是在低級方案下輪替生成的，則不會自動恢復這一權限範圍；請創建新金鑰。
限制金鑰
| 限制 | 適用金鑰 | 可在 API Keys 頁面設定 | 可透過金鑰管理 API 設定 | 拒絕結果 |
|---|---|---|---|---|
| 允許的來源 | 可公開使用的金鑰 | 是 | 是（allowed_origins） | 交換時回傳 403 origin_not_allowed |
| 允許的產品 | 所有金鑰 | 否 | 是（allowed_products） | 可公開使用的金鑰在交換時回傳 403 product_not_allowed；伺服器或舊版金鑰在每次運行時要求中回傳該錯誤。請參閱產品限制。 |
| IP 允許清單 | 伺服器金鑰和舊版金鑰 | 否 | 是（allowed_ips） | 403 ip_not_allowed |
| 每月上限 | 所有金鑰 | 否 | 是（monthly_cap_tokens） | 429 quota_exceeded |
| 到期時間 | 所有金鑰 | 否 | 是（expires_at） | 指定日期之後回傳 401 |
| 權限範圍 | 所有金鑰 | 否 | 僅在創建時設定（scopes） | 403 insufficient_scope |
允許的來源。 最多 100 項，每項格式為 scheme://host[:port]，不包含路徑。可公開使用的金鑰的清單為空表示允許任何來源。詳情及失敗條件請參閱 CORS 與允許的來源。
IP 允許清單。 最多可以添加 100 個 IP 地址或 CIDR 網段。涵蓋所有地址的網段（/0）會被拒絕；如果要允許任意地址，請將清單留空。如果金鑰配置了允許清單，但無法確定調用者的地址，要求也會被拒絕。
每月上限。 限制一把金鑰在一個計費週期內能夠消耗的組織 AI 積分數量。詳情請參閱額度與速率限制。
已核發的工作階段如何受到變更影響
每次要求都會重新檢查工作階段關聯的原始金鑰，因此撤銷權限能夠迅速生效。但增加權限需要重新交換工作階段。
| 金鑰或賬戶變更 | 對已發放工作階段的影響 |
|---|---|
| 金鑰被撤銷，或輪替時沒有寬限期 | 下一次要求回傳 401。 |
| 工作階段來源被移出金鑰的允許來源清單 | 下一次要求回傳 401。 |
| 工作階段對應產品被移出金鑰的允許產品清單 | 下一次要求回傳 401。 |
| 方案降級 | 降級前發放的工作階段回傳 401。降級後交換的工作階段訪問方案已不再支持的功能時，回傳 403 tier_capability_not_allowed。 |
| 新增或降低每月上限 | 下一次要求起生效。 |
| 移除每月上限 | 下一次交換工作階段後生效。 |
| 方案升級 | 下一次交換工作階段後生效。 |
由於工作階段僅持續幾分鐘，因此等待“下一次交換”通常不會太久。SDK 會在刷新時自動應用變化，無需修改代碼。
金鑰管理 API
您可以在 kaleidr.com/api-keys 的 API Keys 頁面設定金鑰名稱、類型及允許的來源。本文介紹的其他設定均透過該頁面使用的同一套 API 完成。
- 基礎 URL：
https://api.kaleidr.com/shared-api/api-keys - 身分驗證： 透過
Authorization: Bearer發送已登錄 Kaleidr 賬戶的訪問權杖，且該賬戶必須是組織的所有者或管理員。此處不接受平台金鑰。目前沒有專門用於金鑰管理的長期有效憑證。 - 組織： 不指定組織時，預設使用您的主要組織。若要指定其他組織，創建金鑰時請在 JSON 要求本文中傳入
org_id；其他所有路由則透過查詢參數?org_id=傳入。創建路由中的org_id查詢參數會被忽略。
| 方法和路徑 | 用途 | 成功回應 |
|---|---|---|
POST / | 創建金鑰 | 201，金鑰對象及 plaintext_key |
GET / | 列出活躍金鑰，按新到舊排序 | 200 |
GET /{id}/events?limit=1..200 | 查看金鑰審計事件 | 200 |
PATCH /{id} | 修改限制條件 | 200，金鑰對象 |
POST /{id}/rotate | 替換金鑰 | 201，新金鑰及 plaintext_key |
POST /{id}/revoke | 撤銷金鑰 | 200，金鑰對象 |
沒有刪除金鑰的路由；如需停用，請撤銷金鑰。
創建金鑰時支持以下欄位：
| 欄位 | 類型 | 預設值 | 說明 |
|---|---|---|---|
name | 字符串，1 至 200 個字符 | 必填 | |
org_id | UUID | 您的主要組織 | 要創建金鑰的組織。必須放在要求本文中；此路由忽略查詢參數。 |
key_type | "publishable" 或 "server" | "publishable" | Free 方案不支持 "server"，會回傳 403 free_plan_publishable_only。 |
environment | "live" 或 "test" | "live" | |
scopes | 字符串陣列 | ["ai", "maps", "design"] | 可用值為 ai、maps、design、vendor。其他值會回傳 422 unknown_scope。方案不支持的權限範圍（例如 Enterprise 以下的 vendor）會回傳 403 tier_capability_not_allowed。 |
allowed_origins | 字符串陣列，最多 100 項 | [] | 對可公開使用的金鑰，空清單表示允許任何來源。 |
allowed_products | 字符串陣列 | [] | 可選 chat、editor、viewer、tile。空清單表示全部。其他值回傳 422 unknown_product。該設定適用於可公開使用的金鑰、伺服器金鑰和舊版金鑰；請參閱產品限制。 |
allowed_ips | 字符串陣列，最多 100 項 | [] | IP 地址或 CIDR 網段。 |
monthly_cap_tokens | 整數，0 或更大 | 無 | 1 或更大的值會限制金鑰；0 或 null 表示無上限。 |
expires_at | 未來的日期和時間 | 無 | |
vendor_acknowledged | 布林值 | false | 可公開使用的金鑰包含 vendor 時必填（Enterprise）。 |
PATCH 支持 name、allowed_origins、allowed_products、allowed_ips、monthly_cap_tokens 和 expires_at。僅發送希望更改的欄位；明確指定 null 可以清除該值。不支持 scopes。
rotate 接受 { "grace_hours": 0 }，值範圍為 0 至 8760。替代金鑰繼承舊金鑰的權限範圍，但會移除當前方案不再允許的權限。Free 方案中，替代金鑰總是包含 Free 的全部能力，並且無法輪替伺服器金鑰或舊版金鑰（403 free_plan_publishable_only）。當值為 0 時，舊金鑰及其工作階段立即失效。設定寬限期後，舊金鑰可繼續使用至寬限期結束，期間仍計入方案的活躍金鑰上限，且不可再次輪替。API Keys 頁面預設使用 24 小時寬限期。
上述路由的錯誤請參閱錯誤：金鑰管理。
身分驗證錯誤
401 表示 API 完全不接受此憑證。403 表示 API 識別了您的身份，但拒絕執行要求。這些錯誤均採用 {"detail": "<code>"} 格式。
在瀏覽器中，如果要求因憑證或來源而被拒絕，回應將不包含 CORS 標頭，因此頁面看到的是 CORS 錯誤，而不是回應體。若要求是在後續權限範圍或方案檢查階段被拒絕，頁面可以讀取回應，SDK 會報告 kaleidr session exchange failed (403)。兩種情況下，都應在瀏覽器開發者工具的 Network 選項卡中打開對應要求，查看錯誤代碼。請參閱 CORS 與允許的來源。
| 狀態碼 | 錯誤代碼 | 原因 | 解決方法 |
|---|---|---|---|
| 401 | Invalid or missing API key | 缺少憑證；金鑰不存在、被撤銷或過期；工作階段過期；關聯金鑰被撤銷、失去該來源或產品的權限，或在方案降級前頒發的工作階段；組織被暫停或沒有方案。 | 在 API Keys 頁面檢查金鑰的值和狀態。對於工作階段，請重新交換。 |
| 401 | publishable_requires_session | 可公開使用的金鑰被發送至運行時端點。 | 先交換為工作階段，或從後端使用伺服器金鑰調用。 |
| 403 | publishable_key_required | 用伺服器金鑰或舊版金鑰調用工作階段交換。 | 交換時使用 kld_pk_… 金鑰。 |
| 403 | origin_required | 工作階段交換要求沒有 Origin 標頭。 | 從瀏覽器網頁發起要求。 |
| 403 | origin_not_allowed | 網頁來源不在金鑰的允許來源清單或已發佈地圖的允許域名清單中。 | 將準確的來源加入金鑰，或將域名加入地圖。 |
| 403 | product_not_allowed | 金鑰允許的產品不包括本次產品：交換時指定的 product，或伺服器/舊版金鑰所調用端點歸屬的產品。 | 修改 allowed_products 或使用其他金鑰。 |
| 403 | insufficient_scope | 金鑰創建時未獲得端點或產品需要的權限範圍。 | 使用具備該權限範圍的金鑰。權限範圍無法修改。 |
| 403 | tier_capability_not_allowed | 金鑰有該權限範圍或產品，但當前方案不支持。 | 在 kaleidr.com/billing 更改方案。 |
| 403 | server_key_in_browser | 伺服器金鑰隨 Origin 標頭一起發送。 | 將要求移至後端。如果金鑰曾出現在網頁原始碼中，請輪替金鑰。 |
| 403 | session_origin_mismatch | 工作階段權杖從不同於頒發來源的地址使用，或已發佈地圖工作階段在缺少 Origin 時使用。 | 在實際使用權杖的網頁中重新交換工作階段。 |
| 403 | ip_not_allowed | 帶有 IP 允許清單的伺服器金鑰或舊版金鑰被未獲准的地址使用。 | 從允許的地址發起調用，或更改 allowed_ips。 |
| 403 | chat_disabled | 已發佈地圖交換：地圖的 Kaleidr AI 未開啓所請求的功能。 | 在 Studio 中地圖的 Kaleidr AI 圖塊裡開啓 Control Tower 或 Popup Window。 |
| 403 | owner_has_no_organization | 已發佈地圖交換：地圖所有者沒有組織。 | 所有者必須創建組織或加入組織。 |
| 404 | not_found | 已發佈地圖交換：找不到使用該 ID 的已發佈地圖或分享連結。 | 檢查 ID，並確認地圖已發佈。 |
包括 429 和 5xx 回應在內的完整目錄，請參閱錯誤。
相關文件
- 安全模型：憑證洩露後可能造成的影響。
- CORS 與允許的來源：如何實施允許來源清單。
- 端點：每個權限範圍可調用的功能。
- 獲取 API 金鑰：如何在 API Keys 頁面創建金鑰。