API 密钥与身份验证

Telemetry API 请求使用团队 API 密钥。将密钥视为生产凭证：为指定工作负载创建它，为其提供所需的最小范围，将其存储在源代码控制之外，并在工作负载退出时撤销它。

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

选择最窄的范围

Telemetry支持三种范围：

仅发出事件的应用程序通常需要 write。报告作业通常需要 read。避免为浏览器、移动应用程序、公共存储库或用户编写的脚本提供团队密钥。

发送密钥

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-and-write 密钥时同时练习摄取和查询路径。

如果密钥出现在提交、日志、屏幕截图、提示或公共客户端捆绑包中，请将其视为已泄露。立即撤销它，替换它，并检查受影响的团队表和查询活动。

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