# 凭证与 Key

01Spatial 使用不同凭证表达“谁在请求”和“请求哪个资源”。不要把 API Key、Map Key、Project Key 和 Portal 登录令牌混为一谈。

| 凭证 | 作用 | 获取位置 |
| --- | --- | --- |
| **API Key** | 标识调用 API 的用户，决定其可访问的资源。 | Portal 个人资料。 |
| **Map Key** | 指向一张具体地图的加密资源标识。 | Ready 地图卡片。 |
| **Project Key** | 指向整个 Project，用于在多张地图中定位。 | Spatial Maps 的 Project 信息区。 |
| **登录令牌** | Portal 管理操作的浏览器会话凭证。 | 登录后由 Portal 管理，不应复制到客户端。 |

## 选择 Map 或 Project

- 单地图应用发送 `api_key + map_key`，范围明确，适合作为默认生产方式。
- 跨地图应用发送 `api_key + project_key`，由服务在 Project 内选择地图。
- 同一个定位请求不能同时发送 `map_key` 和 `project_key`。
- API Key 必须属于有权访问目标地图或 Project 的用户。

## 安全使用

- 不把 Key 放在公开 Git 仓库、客户端日志、分析事件或工单截图中。
- 不把 Key 放在普通网页 URL 中；表单或请求体优先于 query。Space Studio 生成的 AR 启动链接是受控预览入口，不应公开转发。
- 浏览器或移动端无法真正保密内置凭证。面向公众的应用应通过受控后端、短期授权或正式发布入口限制滥用。
- 开发、测试和生产环境使用各自的 Key；Map Key 只能由生成它的 Portal 环境解析。

## 轮换与失效

在个人资料中重新生成 API Key 会让旧 Key **立即失效**。轮换前先列出全部客户端和服务，更新安全配置后分阶段发布，最后验证旧 Key 已不再使用。

Map Transfer 接受后，Map Key 保持不变，但访问它的 API Key 必须属于新的所有者。地图删除后 Map Key 不再可用。