API 密钥与身份验证

Telemetry API 请求接受匿名试用密钥或团队 API 密钥。密钥应保密，并且只在可信的服务端代码中使用。唯一的例外是仅摄取密钥：它只能发送事件，可以安全地嵌入浏览器、移动应用或 CLI。

从匿名密钥开始

首页在设置提示词中提供 anon_… 密钥。无需账户即可写入事件、执行 SQL 查询和读取表元数据。查询在首个事件后可用 24 小时。请在 7 天内创建账户以保留数据。没有事件的试用在创建 7 天后到期。

注册会识别同一浏览器中的试用。如果更换了浏览器或丢失了私密关联链接，请选择已有匿名 API 密钥？，粘贴密钥并点击查找我的数据。然后注册，或登录已有账户并在保留我的数据中确认关联。事件仍在原工作区，原密钥仍有效。已到期的试用无法恢复。

管理账户密钥

为明确的任务创建密钥，只授予所需的最低权限，将其保存在版本控制之外，并在任务停用时撤销。

打开 团队设置 → API 密钥 以创建或管理密钥。完整值是凭证，因此将其复制到目标机密管理器而不是共享文档或问题中。

选择最窄的范围

Telemetry支持三种范围：

仅发出事件的应用程序需要 ingest。报告作业需要 read。只有 read-and-write 密钥可以删除数据、更改保留期或分区、删除表，或创建和更改仪表板与告警，因此切勿将其放入浏览器、移动应用程序、公共存储库或用户编写的脚本。2026 年 10 月之前创建的“仅写入”密钥现在是 ingest 密钥。

发送密钥

HTTP 端点接受密钥作为原始 Authorization 值或不记名令牌：

curl https://api.telemetry.sh/tables \
  -H "Authorization: Bearer $TELEMETRY_API_KEY"

SDK 初始化接受相同的 API 密钥。在服务端代码中，请通过环境变量或密钥管理器读取密钥：

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

不要通过 NEXT_PUBLIC_ 等公开构建变量或客户端配置，公开匿名试用、read 或 read-and-write 密钥。只发送事件的客户端可以使用 ingest 密钥。请在 团队设置 → API 密钥 中选择 Ingest only（仅摄取） 权限，并在将密钥放入公开版本前确认其权限。

仅摄取密钥无法查询自己发送的事件，也无法管理工作区。请在 Telemetry 仪表板中确认应用的事件，或在可信的服务端脚本中使用另一把 read 密钥。不要将读取密钥放入客户端。只记录您确实打算发送的字段；仅写入权限不代表可以安全地收集私密数据。

按工作负载分离密钥

使用不同的密钥进行生产摄取、暂存、计划报告和编码代理设置。特定于工作负载的密钥使轮换和事件响应更小：撤销一个报告密钥不应中断事件摄取。

以密钥的所有者和用途命名密钥。记录密钥的部署位置、范围以及预期的轮换所有者，而不记录密钥值本身。

安全地旋转和撤销

首先创建替换密钥，将其部署到工作负载，验证成功的请求，然后撤销之前的密钥。旋转 read-and-write 密钥时同时练习摄取和查询路径。

如果私密密钥出现在提交、日志、截图、提示词或公开客户端代码中，请将其视为已泄露。立即撤销并替换它，然后检查受影响的团队数据表和查询活动。刻意嵌入公开客户端的 ingest 密钥仍然只有写入权限，但任何获取它的人都能发送事件。如果密钥遭到滥用，请撤销并替换它。

继续使用 日志API、查询API 和 敏感数据指导。