获取 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 的工作原理：会话、组织和两类使用配额。
- 身份认证与权限：各类凭据的发送和验证方式。
- 生产环境检查清单：每个网站独立密钥、允许来源和发布前准备。