取得 API 金鑰
API 金鑰用於向 Kaleidr 標識您的組織。使用該金鑰從瀏覽器或服務器傳送的每項請求，都會根據組織當前方案進行授權，並計入組織的使用量。您可以在 kaleidr.com/api-keys 建立和管理金鑰。
使用 Chat、Editor、Tile 或調用服務器 API 都需要金鑰。但通過 Viewer 嵌入已發佈地圖不需要金鑰，只需地圖 ID 即可。
兩種金鑰類型
金鑰分為兩種類型，應根據使用金鑰的代碼在哪裡運行來選擇。
| 可公開金鑰 | 服務器金鑰 | |
|---|---|---|
| 前綴 | kld_pk_live_… | kld_sk_live_… |
| 運行位置 | 網頁：SDK 和 <kaleidr-map> 元素 | 僅限您的服務器 |
| 能否安全地放在網頁原始碼中 | 可以 | 不可以。應像密碼一樣保護。 |
| 使用方式 | SDK 將其交換為短期工作階段權杖，由工作階段發起請求 | 每次請求通過 Authorization: Bearer 或 X-Api-Key 直接傳送 |
| 可限制的範圍 | 允許的來來源網站清單 | 通過金鑰 API 設定的各種限制，如允許的 IP 地址清單 |
| 方案 | Free、Pro、Enterprise | Pro、Enterprise |
| API Keys 頁面中的名稱 | Browser / Embed Key | Server Key |
在訪客瀏覽器中運行的代碼應使用可公開金鑰。 這種金鑰本來就允許公開。保護機制包括允許的來來源清單，以及不能直接調用 API：將可公開金鑰直接傳送到 API 端點時，請求會被拒絕並傳回 401 publishable_requires_session。
後端調用 Kaleidr 時應使用服務器金鑰，例如執行地址地理編碼、通過 API 路由向前端流式傳輸回答，或為移動應用提供後端服務。包含 Origin 標頭的服務器金鑰請求會被拒絕並傳回 403 server_key_in_browser，因為瀏覽器會傳送此標頭。SDK 也會在發出任何請求前拒絕使用服務器金鑰掛載。切勿將服務器金鑰放入網頁或移動應用安裝包。
兩種金鑰屬於同一組織，並共享使用配額。有關工作階段、組織和計費方式，請請參閱 Kaleidr 的工作原理。
在引入這兩種金鑰類型之前建立的舊金鑰以 kld_live_ 開頭。它們仍可正常使用，並像服務器金鑰一樣直接傳送。
各方案允許的功能
組織的方案決定它能夠建立哪些類型的金鑰、金鑰可以攜帶哪些權限，以及能掛載哪些產品。
| 方案 | 可公開金鑰 | 服務器金鑰 | 允許的權限範圍 | 允許的產品 |
|---|---|---|---|---|
| Free | 是 | — (403 free_plan_publishable_only) | ai、maps、design | chat、editor、viewer、tile |
| Pro | 是 | 是 | ai、maps、design | chat、editor、viewer、tile |
| Enterprise | 是 | 是 | ai、maps、design、vendor* | chat、editor、viewer、tile |
* vendor 預設不會包含，且只有 Enterprise 金鑰才能擁有。請參閱權限範圍。
每個方案還限制組織可持有的有效金鑰數量：
| 方案 | 有效金鑰數 |
|---|---|
| Free | 2 |
| Pro | 10 |
| Enterprise | 25 |
超過限制後，建立金鑰會被拒絕並傳回 409 key_limit_reached；請撤銷舊金鑰後再建立新金鑰。輪替金鑰不視為新建，但舊金鑰在寬限期結束前仍計入數量限制。
請注意關於此表的五點說明：
- Free 支持所有瀏覽器產品。 Free 組織可以在網站中使用 Chat、Editor、Tile 和 Viewer。Chat 回答會消耗方案的每月 AI 積分；耗盡後，請求傳回 429，直到下個計費週期、購買附加包或升級方案。
- Viewer 列在表中表示方案支持它，並不意味著需要金鑰。 所有方案都能無需金鑰嵌入已發佈的地圖。
- Pro 增加服務器金鑰和金鑰數量。 Pro 組織可以為後端建立服務器金鑰，並且最多持有 10 個有效金鑰，而非 2 個。支持的權限和產品與 Free 相同。
- 在 AI 回答中使用自有業務資料僅限 Enterprise，上傳和訪問均如此。 Enterprise 組織的所有者或管理員可在合同限制內上傳業務資料，Kaleidr Studio 助手可向該組織已登入成員提供基於這些資料的回答。Free 和 Pro 不能上傳。通過 API 或 SDK 使用帶
vendor權限的金鑰讀取這些資料也僅限 Enterprise。在 Free 或 Pro 請求建立含vendor的金鑰會傳回 403tier_capability_not_allowed。詳見您的資料。 - 所有方案都能向 Kaleidr Studio 地圖添加資料集。 登入使用者可在 Data 面板上傳電子錶格和地理資料檔案。Free 的限制為每個資料集 50,000 行、每個檔案 32 MiB、組織合計 250,000 行；Pro 為 100,000 行、64 MiB、合計 5,000,000 行；Enterprise 單個資料集和檔案限制與 Pro 相同（100,000 行和 64 MiB），組織總量由合同規定。這些資料會顯示在 Studio 地圖和已發佈地圖上，Studio AI 助手也可就其回答問題；但無法通過 API 金鑰讀取。請參閱地圖上的資料集。
各方案價格和配額見價格頁面。Enterprise 配額可定制，並在合同中約定。
權限範圍
權限範圍（scope）是金鑰攜帶的授權。每個產品或端點都會檢查所需權限。
| 權限 | 允許的操作 | 新金鑰中是否包含 |
|---|---|---|
ai | Chat 以及服務器 API 的聊天、地點和地理編碼端點 | 包含 |
maps | Tile 底圖工作階段 | 包含 |
design | Editor 和服務器 API 的設計端點 | 包含 |
vendor | 讓 Chat 回答能夠利用組織已發佈的業務資料 | 不包含；需要專門申請。僅 Enterprise。 |
通過 API Keys 頁面建立的金鑰始終包含 ai、maps 和 design，頁面上沒有權限選擇器。如需申請 vendor（僅 Enterprise），或排除某個預設權限，請使用金鑰 API。
權限在建立金鑰時固定。 之後不能編輯。輪替金鑰通常保留原權限，但有兩種例外：當前方案不再允許的權限會從新金鑰中移除；在 Free 上輪替後，新金鑰始終包含 Free 的全部權限（請參閱方案變更）。如需更改權限，請建立新金鑰並撤銷舊金鑰。
方案變更時
金鑰實際可執行的操作，取決於其所攜帶的權限與當前方案允許功能的交集；每次請求都會進行檢查。
從 Enterprise 降至 Pro 或 Free。 已有金鑰繼續有效。帶 vendor 的金鑰仍保存該權限設定，但權限不再生效：回答不再使用您的業務資料，也不會報錯，請求仍可成功並基於通用知識回答。升級前簽發的瀏覽器工作階段將終止，其下一次請求傳回 401，SDK 隨後根據新方案獲取新工作階段。在 Pro 輪替該金鑰時，新金鑰將不含 vendor，其他權限和產品清單不變。組織也無法繼續上傳業務資料：上傳請求傳回 403 vendor_data_not_on_plan。所有者和管理員仍可列出、取消發佈及刪除之前上傳的版本。
降至 Free。 Free 組織不能建立服務器金鑰，也不能輪替已有服務器金鑰或舊版金鑰，否則傳回 403 free_plan_publishable_only。在 Free 輪替可公開金鑰會生成擁有完整 Free 權限的新金鑰（ai、maps、design 和全部四種產品），不受舊權限限制。已添加到 Studio 地圖的資料集會保留；新的上傳需遵守 Free 的資料集限制。之前的瀏覽器工作階段同樣會終止，SDK 會重新獲取。
重新升級方案後，允許的功能會恢復。如果金鑰設定中仍保留 vendor，升回 Enterprise 後即可重新訪問相關資料。但如果金鑰曾在較低方案中輪替，新金鑰不會自動重新獲得該權限；需要另建金鑰。
建立金鑰
您必須是組織的所有者或管理員。
- 登入 kaleidr.com，打開 kaleidr.com/api-keys。頁面在 Your API Keys 下列出組織的金鑰。
- 點擊 Create Key，打開包含三個字段的 Create a Key 對話框。
- Key Name。 輸入便於識別的名稱，例如
Production site。訪客看不到此名稱。建議按使用位置命名，便於日後撤銷時區分。 - Key Type。 選擇 Browser / Embed Key（可公開）或 Server Key（服務器）。Free 方案不顯示 Server Key 選項。建立後不能更改類型。
- Allowed Origins。 對可公開金鑰，輸入允許使用它的網站，並用逗號分隔，例如
https://www.example.com, https://app.example.com。留空表示允許所有網站。格式詳見允許的來來源。服務器金鑰不綁定網站，應留空。 - 點擊 Create Key。
- 立即複製金鑰。 對話框僅顯示一次完整值，並提示“Copy this key now — it won't be shown again.”。點擊 Copy，妥善保存後點擊 Done。Kaleidr 不保存完整金鑰值。丟失後須輪替金鑰獲取新值。
預期結果： 新金鑰會顯示在表格中，Key 列展示前幾位字符，並列出名稱、類型（Browser 或 Server）、Active 狀態和當天日期。
如果頁面顯示 "You must be an organization admin to manage API keys."，請讓組織所有者或管理員建立金鑰或調整您的角色。
允許的來源
允許的來來源指可公開金鑰能夠運行的網站。SDK 將金鑰交換為工作階段時，瀏覽器會在 Origin 標頭中傳送網頁的來來源，Kaleidr 再與清單比較。
- 空清單允許所有網站。 開發時較方便，但任何從網頁來源碼複製金鑰的人，都可以在自己的網站使用它並消耗您的配額。每個生產環境金鑰都應配置來來源清單。
- 至少有一項的清單只允許列出的來來源。 必須完全匹配：
https://example.com不包括https://www.example.com；http://localhost:3000也不包括http://localhost:5173。請逐項添加。
來來源由協議、主機和可選端口組成，不包含路徑：
| 輸入項 | 是否接受 |
|---|---|
https://www.example.com | 是 |
https://app.example.com:8443 | 是 |
http://localhost:8000 | 是。http 僅允許用於 localhost 和 127.0.0.1。可通過金鑰管理 API 設定 http://[::1]，但不能在本頁面設定。 |
http://www.example.com | 否。本地以外網站必須使用 https。 |
https://www.example.com/store | 否。來來源不能包含路徑。 |
*.example.com | 否。不支持通配符。https://*.example.com 會原樣保存，但不會匹配任何網站。 |
每個金鑰最多可配置 100 個來來源。
修改清單時，點擊金鑰 所在行的編輯（鉛筆）按鈕。在 Edit Key 對話框中修改 Allowed Origins，然後點擊 Save changes。也可以在該對話框修改金鑰名稱。
- 添加來來源後，該網站新建立的工作階段即可使用。
- 移除來來源會阻止該網站。此前向該來來源簽發的工作階段在下一次請求時立即傳回 401
Invalid or missing API key，不會一直有效到自然過期。
被阻止的網站會出現甚麼情況。 當來來源不在清單中的網頁嘗試掛載產品時，工作階段交換傳回 403 origin_not_allowed。回應不包含 CORS 標頭，因此瀏覽器對 …/b2b/v1/sdk/sessions 報 CORS 錯誤，SDK 記錄 [kaleidr:<product>] 錯誤，不會渲染任何內容。確切錯誤文本見故障排查。
允許來來源清單可以限制金鑰在瀏覽器中使用的網站，但無法讓可公開金鑰保密。非瀏覽器客戶端可以傳送任意 Origin 值。安全模型解釋它能保護甚麼和不能保護甚麼；CORS 與允許的來來源說明請求細節。
輪替與撤銷金鑰
輪替金鑰可在不中斷服務的情況下替換金鑰值。選擇金鑰行中的輪替操作並確認。Kaleidr 簽發類型、權限和允許來來源均相同的新金鑰，僅顯示一次完整值。舊金鑰仍可使用 24 小時，方便您部署新值。在此期間舊金鑰仍計入方案金鑰數量限制，且不能再次輪替。
有權訪問金鑰的成員離開團隊時，或根據安全策略的週期，可以輪替金鑰。但若金鑰已洩露，應撤銷而不是輪替：從本頁面輪替會讓舊值再有效 24 小時。
撤銷金鑰可立即停止其使用。選擇金鑰行中的刪除（垃圾桶）按鈕並確認。頁面警告：“Revoke this API key? Any site using it will stop working immediately.”。撤銷也會終止該金鑰簽發的全部工作階段，已打開的頁面會在下次請求時失效。撤銷的金鑰不能恢復。
如果洩露的是服務器金鑰，應直接撤銷，不要輪替，否則 24 小時寬限期會繼續允許洩露的金鑰使用。
測試金鑰
兩種金鑰都有測試版本：kld_pk_test_… 和 kld_sk_test_…。
測試金鑰並不代表沙盒環境。 它調用相同的 API、獲得相同的答案，也像正式金鑰一樣消耗 AI 積分和地圖加載量。唯一不同之處是測試金鑰不能加載底圖圖磚。
測試金鑰的價值在於隔離環境：預發佈網站的流量使用專屬金鑰，撤銷該金鑰不會影響生產環境。不要認為測試流量免費。
API Keys 頁面只能建立正式金鑰。要建立測試金鑰，請通過金鑰 API 提交 "environment": "test"。
金鑰管理頁面未提供的選項
API Keys 頁面可設定名稱、類型和允許來來源。更多配置可通過 https://api.kaleidr.com/shared-api/api-keys 的金鑰 API 完成。
金鑰 API 驗證的是您的使用者身份，不是某個 API 金鑰。請以 Authorization: Bearer 傳入已登入組織所有者或管理員的訪問權杖。API 金鑰本身不能建立或修改金鑰。
| 字段 | 類型 | 預設值 | 作用 |
|---|---|---|---|
name | 字符串，1–200 個字符 | 必填 | 金鑰的名稱。 |
org_id | UUID | 您的主要組織 | 建立金鑰的所屬組織。應放在請求正文中；建立時忽略查詢參數 org_id。 |
key_type | "publishable" 或 "server" | "publishable" | 金鑰類型，建立後不可修改。 |
environment | "live" 或 "test" | "live" | 建立正式或測試金鑰，建立後不可更改。 |
scopes | 字符串陣列 | ["ai", "maps", "design"] | 金鑰的權限範圍，建立後固定。 |
vendor_acknowledged | 布林值 | false | 建立帶 vendor 權限的可公開金鑰時必須為 true。 |
allowed_origins | 字符串陣列，最多 100 個 | [] | 允許的來來源，僅適用於可公開金鑰。 |
allowed_products | 字符串陣列 | []（全部產品） | 限制為 chat、editor、viewer、tile 中的部分產品。適用於所有金鑰類型；見下方說明。 |
allowed_ips | 字符串陣列，最多 100 個 | []（任何地址） | 服務器金鑰允許的 IP 地址或 CIDR 網段。 |
monthly_cap_tokens | 大於或等於 0 的整數 | 無 | 此金鑰每個計費週期可消耗的 AI 積分上限。1 以上表示設定上限；0 或 null 表示無限制。 |
expires_at | 未來的日期時間 | 無 | 金鑰停止生效的時間。 |
Free 方案的 scopes 和 allowed_products 始終包含方案允許的全部項目（ai、maps、design；chat、editor、viewer、tile），無論請求提供甚麼，輪替時同樣如此。在所有方案中，申請不被允許的權限或產品都會被拒絕並傳回 403 tier_capability_not_allowed，而不是無提示地忽略。
產品限制適用於金鑰的所有使用場景。 如果可公開金鑰只允許部分產品，卻嘗試掛載其他產品，工作階段交換會傳回 403 product_not_allowed。受限制的服務器金鑰或舊版金鑰調用其他產品的端點時，每次請求也會傳回 403 product_not_allowed：聊天、地點、地理編碼端點屬於 chat，設計端點屬於 editor。如果服務器金鑰應訪問權限允許的所有端點，請將 allowed_products 留空。對應關係見認證與權限中的產品限制表。
以下請求在一個預發佈網站上建立僅限 Chat 使用的可公開測試金鑰：
curl -X POST https://api.kaleidr.com/shared-api/api-keys \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Staging site chat",
"key_type": "publishable",
"environment": "test",
"allowed_origins": ["https://staging.example.com"],
"allowed_products": ["chat"]
}'
201 回應包含金鑰配置，並且僅此一次在 plaintext_key 中傳回完整金鑰值：
{
"id": "5f0c2a9e-…",
"name": "Staging site chat",
"key_prefix": "kld_pk_test_…",
"key_type": "publishable",
"environment": "test",
"scopes": ["ai", "maps", "design"],
"allowed_origins": ["https://staging.example.com"],
"allowed_products": ["chat"],
"allowed_ips": [],
"monthly_cap_tokens": null,
"status": "active",
"expires_at": null,
"plaintext_key": "kld_pk_test_…"
}
可讀取企業業務資料的金鑰
vendor 權限允許 Chat 利用組織已發佈的業務資料回答問題。上傳這些資料和擁有可通過金鑰讀取資料的權限都僅限 Enterprise；該權限只能通過金鑰 API 授予：
curl -X POST https://api.kaleidr.com/shared-api/api-keys \
-H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Site chat with our data",
"key_type": "publishable",
"scopes": ["ai", "vendor"],
"vendor_acknowledged": true,
"allowed_origins": ["https://www.example.com"]
}'
設定 vendor_acknowledged 是因為可公開金鑰存在於網頁原始碼中：任何能夠打開網頁的人都能向 Chat 提問，而回答可能包含您上傳的資料。將此字段設為 true 表示您明確知曉並同意這種訪問方式。
- 可公開金鑰請求
vendor，但未提供"vendor_acknowledged": true，會被拒絕並傳回 422vendor_scope_requires_acknowledgement。 - 服務器金鑰無需確認。
- Free 和 Pro 方案包含
vendor的申請會傳回 403tier_capability_not_allowed，無論是否提供vendor_acknowledged，都不會建立金鑰。
您的資料介紹如何上傳，以及如何確認回答是否使用了這些資料。
修改金鑰（PATCH /shared-api/api-keys/{id}）時可提交 name、allowed_origins、allowed_products、allowed_ips、monthly_cap_tokens 和 expires_at。輪替金鑰（POST /shared-api/api-keys/{id}/rotate）接受 0 到 8760 的 grace_hours；預設 0 意味著舊金鑰立即失效。撤銷使用 POST /shared-api/api-keys/{id}/revoke。這些操作的拒絕代碼見錯誤。
每個嵌入都必須符合的兩項前提條件
即使金鑰正確，需要金鑰的產品也未必能渲染。網頁本身必須滿足另外兩個條件，而瀏覽器的報錯不一定會直接指出原因。
1. 從金鑰允許的來源提供頁面
- 開發期間也應通過 HTTP 或 HTTPS 提供網頁。 直接從磁盤打開的檔案（
file://）沒有可添加到金鑰允許清單的來來源。 - 如果金鑰指定了允許來來源，網頁的來來源必須與清單完全一致，包括協議、主機和端口。本地開發通常需要
http://localhost:<port>。
如果條件不滿足，頁面不會渲染內容，控制台在工作階段交換時顯示 CORS 錯誤。表面上像網絡問題，實際上是允許來來源清單配置錯誤。
2. 內容安全政策允許載入產品資源
如果網站傳送 Content-Security-Policy 標頭，就必須允許各產品需要的 Kaleidr 主機。沒有傳送該標頭的網站無需配置。
| 產品 | 策略必須允許的資來源 |
|---|---|
| Viewer、Tile | 來自 https://cdn.kaleidr.com 的腳本、來自 https://map-embed.kaleidr.com 的 iframe，以及使用金鑰掛載時連接 https://api.kaleidr.com |
| Chat、Editor | 來自 https://cdn.kaleidr.com 的腳本、連接 https://api.kaleidr.com，以及內聯樣式，因為兩者都向網頁添加樣式。Editor 還從 https://tile.kaleidr.com 加載底圖。 |
內容安全策略逐一列出了各產品所需的完整指令。
配置不正確時，瀏覽器會報告 Refused to load… 或 Refused to connect…，並指出被阻止的地址和策略指令。
使用金鑰
在網頁中，向產品傳入可公開金鑰。SDK 將其交換為工作階段，並在產品保持掛載期間不斷續期。
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map
product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="display:block; height:480px"
></kaleidr-map>
預期結果： 底圖出現，Network 分頁顯示來自 https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions 的 200 回應。快速入門提供各產品的完整示例網頁。
在服務器中，每次請求都傳送服務器金鑰。以下調用可列出設計端點支持的地圖樣式，不消耗 AI 積分，因此適合首次驗證金鑰是否有效。
curl https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
-H "Authorization: Bearer kld_sk_live_…"
預期結果： 傳回 200 和包含 styles 陣列的 JSON 對 象。若傳回 401 以及 {"detail":"Invalid or missing API key"}，表示金鑰值錯誤或已撤銷。若傳回 403 以及 {"detail":"server_key_in_browser"}，表示請求攜帶 Origin 標頭，應將其移除。之後請參閱服務器快速入門。
後續步驟
- 快速入門：為 Chat、Viewer 和 Tile 分別提供可運行的網頁。
- Kaleidr 的工作原理：工作階段、組織和兩類使用配額。
- 身份認證與權限：各類憑據的傳送和驗證方式。
- 生產環境檢查清單：每個網站獨立金鑰、允許來來源和發佈前準備。