获取 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​

使用方法​