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 和 敏感資料指導。