> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 密钥与安全

> BeatAPI 密钥的创建、分发、轮换与吊销，以及密钥绝对不能出现在哪些地方。

# 密钥与安全

## 在哪创建密钥

[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)。**显示时就要复制下来**，之后不会再展示第二次。

## 该建几把密钥

**每个会调用 BeatAPI 的东西各一把** —— 每个应用、每个工具、每个环境。

成本为零，好处立竿见影：`GET /v1/usage` 的 `by_api_key` 不需要任何埋点就能归集成本；某把密钥泄露或行为异常时，可以单独吊销而不影响其他。

开发、预发、生产**绝不应该共用一把密钥**。

## 密钥绝对不能放在哪

任何用户或陌生人能读到的地方：

* 浏览器 JavaScript 或任何前端打包产物。**发到浏览器的东西就是公开的。**
* 移动应用。反编译是常规操作。
* 公开仓库，以及未来有可能开源的私有仓库。
* 日志、错误上报、截图与工单。
* URL 查询参数 —— 它会被代理、浏览器历史和服务器日志记录下来。

**唯一正确的位置是请求头**：`Authorization: Bearer <密钥>`。

## 怎么让密钥不进仓库

用环境变量，并把设置它的文件排除在版本控制之外：

```bash
read -rsp "BeatAPI 密钥: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY
```

这样读入还能顺带避免它进入 shell 历史。把 `.env`、`~/.codex/auth.json` 以及任何存有密钥的工具配置加进 `.gitignore`。

支持环境变量的集成，优先用环境变量而不是把密钥写进配置文件 —— [Codex CLI](/integrations/codex-cli) 提供 `env_key` 正是为此。

## 密钥泄露了怎么办

**先吊销，再换新。** 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)吊销旧密钥，然后创建新的并更新用到它的地方。吊销立即生效。

**顺序不能反。** 先换新、稍后再吊销，中间那段窗口里泄露的密钥仍然在花你的余额。

处理完后，到 `GET /v1/usage` 的 `by_api_key` 里检查有没有你不认识的用量。

## 多久轮换一次

按你真能坚持的周期来；另外，只要有能接触密钥的人离职、或密钥有暴露嫌疑，就立即轮换。按组件分密钥能让轮换变得很便宜，因为每把只牵动一处部署。

## 浏览器能直连 BeatAPI 吗

**带 API 密钥不行。** 实时 API 的做法是：由你的服务端创建会话，再把一个仅限该会话、短期有效的 `client_secret` 交给浏览器 —— 见[实时 API](/realtime-api)。其余所有端点都只限服务端调用。

生成的媒体产物是个例外，且仅限读取：任务产物地址在查询参数里自带签名凭据，只对那一个对象有效，所以浏览器可以用 `<img>` 或 `<video>` 直接加载，不需要附加任何请求头。

## 你们会拿我的数据训练吗

**不会。** 在发送人脸、声音等个人数据前，以及代他人处理数据前，请阅读[隐私政策](https://beatapi.io/privacy-policy)与[服务条款](https://beatapi.io/terms-of-service)。

## 怎么确认回调确实来自 BeatAPI

**按原始字节校验签名，在解析 JSON 之前。** 重新序列化会改变字节，签名就对不上了。同时校验时间戳，防止旧的推送被重放。详见 [Webhook 回调](/webhooks)。

一个不校验签名的回调端点，等于给你的系统开了一条不需要鉴权的写入通道。**签名校验失败要当成攻击处理，不是当成 bug。**

## 你们记录什么

请求会带 `request_id` 记录，用于支持与计费。报障时请提供这个编号，**永远不要提供密钥本身**。