取得 API 金鑰

Kaleidr 是一個平台、一個 SDK 與一個存取系統 — AI、地圖與設計功能透過能力範圍進行控制。依照運行位置，金鑰提供兩種安全形式；兩者皆屬於同一個組織，並使用相同的配額池。

形式	前綴	運行位置	功能
Publishable（瀏覽器）	`kld_pk_live_…`	HTML、SDK、`<kaleidr-map>` 中	受來源限制，可安全地出現在頁面原始碼中。SDK 會在運行時將其交換為短期工作階段。不能作為伺服器 bearer 使用，也不能管理金鑰。
Server（後端）	`kld_sk_live_…`	僅限您的伺服器	用於伺服器對伺服器呼叫的完整 bearer；支援選用 IP allowlist、限制與到期時間。瀏覽器中會被阻擋（403 `server_key_in_browser`）。

現有舊版 kld_live_… 金鑰會繼續正常驗證，無需變更。

各方案允許的內容

這是標準的方案 → 範圍 × 產品政策。此表與 @kaleidr/shared-types 中的 B2B_TIER_API_CAPABILITIES 保持一致 — 它也是 shared-api 在建立金鑰時以及 inference-api 在工作階段交換時讀取的同一個常數 — 透過 CI drift guard，確保本文中的任何一列都不會悄悄與平台實際允許的內容不一致。

方案	Publishable	Server	允許的範圍	允許的產品
Free	是	— (403 `free_plan_publishable_only`)	`maps`	`tile`
Pro	是	是	`ai`, `maps`, `design`, `vendor`*	`chat`, `editor`, `viewer`, `tile`
Enterprise	是	是	`ai`, `maps`, `design`, `vendor`*	`chat`, `editor`, `viewer`, `tile`

* vendor 需要針對每個金鑰進行明確確認（否則傳回 403 vendor_scope_requires_acknowledgement）。

Viewer 完全不需要金鑰 — share id 本身就是憑證。任何方案（包括 Free）都可以在完全沒有金鑰的情況下嵌入 Viewer。向 Viewer embed 傳遞金鑰會以 product_not_allowed 拒絕。

實際允許範圍 = 已儲存金鑰 × 目前方案。 如果 Pro 金鑰降級為 Free，伺服器會將其交換為符合 Free 權限的工作階段 — 僅允許 maps 範圍與 tile 產品。要重新擴大 Free 金鑰的權限，需要在較高方案中建立新金鑰，而不是編輯現有金鑰（請參閱 Errors — Key management）。

測試金鑰

兩種形式皆提供 test 版本（kld_pk_test_…, kld_sk_test_…）。

測試金鑰不是 sandbox。它使用相同的 API 進行驗證，呼叫相同的模型，並消耗與 live 金鑰相同的每月配額。只有兩點不同：

test publishable 金鑰可以在沒有 origin allowlist 的情況下建立，而 live 金鑰不可以；
test 金鑰不能提供 basemap tiles。

測試金鑰真正的價值在於讓 staging 流量可單獨識別並可獨立撤銷。不要將它們視為免費資源。

建立金鑰

登入並開啟帳戶中的 API Keys (kaleidr.com/api-keys) — 僅限組織管理員使用。
建立金鑰 — 為其命名並選擇 Browser（publishable）或 Server。在 Pro 與 Enterprise 中，金鑰會帶有該方案允許的全部權限（ai, maps, design scopes；chat, editor, viewer, tile products）；在 Free 中，它是僅限 maps / tile 的 Browser 金鑰，不提供 Server 選項。
live Browser 金鑰必須至少綁定一個 allowed origin — 沒有 origin 的 live publishable 金鑰會被拒絕，因為它會成為頁面原始碼中的長期秘密資訊。
僅複製一次 kld_pk_live_… / kld_sk_live_… 的值 — 它只顯示一次，之後不會再次顯示。

每個嵌入都需要的兩個前提條件

目前這兩項都沒有記錄在任何產品頁面中，而任何一項都可能單獨阻止第一次整合。

1. Origin allowlist

工作階段交換會將瀏覽器的 Origin 標頭與金鑰的 allowlist 進行比對。不相符時將傳回 403 session_origin_mismatch。file:// 完全不會傳送 Origin — 而複製程式碼片段後最常見的首次測試方式恰好如此 — 因此所有使用金鑰的嵌入都必須透過 HTTP(S) 提供。

更新現有金鑰的 allowlist 時，應使用 Cognito org-admin JWT，而不是平台金鑰本身：

PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json

{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }

PATCH 會立即使金鑰的 snapshot cache 失效，而且 刪除某個 origin 也會終止已經綁定到它的工作階段 — 每個工作階段要求都會再次根據金鑰目前的 allowed_origins 檢查其 origin，因此來自已刪除 origin 的下一次要求會立即被拒絕，而不會一直運行至 TTL 到期。新增 origin 則相反：它允許新的工作階段，但不會將現有工作階段追溯綁定到該 origin。

2. 客戶 CSP

您的頁面 Content Security Policy 必須允許每個產品載入的資源。請參閱 Content Security Policy 了解各產品的設定 — Tile 與 Viewer 只需要 SDK loader 與一個 frame host； Chat 與 Editor 因為 MapLibre 在父文件中運行，所以還需要 'wasm-unsafe-eval' 以及地圖供應商的 host。

使用方式

在瀏覽器中，傳入 publishable 金鑰，SDK 會將其交換為一個短期工作階段：

<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="height:480px"></kaleidr-map>

從伺服器端，以 bearer 方式傳送 server 金鑰：

Authorization: Bearer kld_sk_live_…

該金鑰會以您的組織身分進行驗證。使用量會計入組織的每月配額。請參閱 Auth & scopes 了解每個範圍可解鎖的功能，並參閱 CORS & allowed origins 了解控制每次工作階段交換的瀏覽器 origin allowlist。

各方案允許的內容​

測試金鑰​

建立金鑰​

每個嵌入都需要的兩個前提條件​

1. Origin allowlist​

2. 客戶 CSP​

使用方式​