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