APIキーと認証

Telemetry API は匿名試用キーとチーム API キーを受け付けます。キーは秘密にし、信頼できるサーバー側のコードでのみ使ってください。唯一の例外は取り込み専用キーです。イベントの送信しかできないため、ブラウザ、モバイルアプリ、CLI に埋め込んでも安全です。

匿名キーで始める

ホームページの設定プロンプトに anon_… キーが含まれます。アカウントなしでイベントの送信、SQL クエリ、テーブルのメタデータ取得ができます。クエリは最初のイベントから24時間利用できます。データを保持するには7日以内にアカウントを作成します。イベントのない試用は作成から7日で期限切れになります。

登録時に同じブラウザーの試用を検出します。ブラウザーを変更した場合や専用リンクを失った場合は、匿名 API キーをお持ちですか？を選び、キーを貼り付けてデータを探すを押します。その後登録するか、既存のアカウントにログインし、データを保持で連携を確認します。イベントは同じワークスペースに残り、元のキーを使い続けられます。期限切れの試用は復元できません。

アカウントのキーを管理する

用途ごとにキーを作成し、必要最小限の権限を付与します。ソース管理の外に保存し、用途がなくなったら失効させます。

開く チーム設定 → API キー キーを作成または管理します。完全な値は資格情報であるため、共有ドキュメントや問題ではなく、ターゲットのシークレット マネージャーにコピーします。

最も狭い範囲を選択する

Telemetry は 3 つのスコープをサポートします。

イベントを送信するだけのアプリケーションには 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);

匿名トライアル、read、read-and-write のキーを、NEXT_PUBLIC_ などの公開ビルド変数やクライアント設定に含めないでください。イベントを送信するだけのクライアントには ingest キーを使えます。チーム設定 → API キー で Ingest only を選び、公開ビルドに含める前に権限を確認してください。

取り込み専用キーでは、送信したイベントのクエリやワークスペースの管理はできません。アプリのイベントは Telemetry のダッシュボードで確認するか、信頼できるサーバー側のスクリプトで別の read キーを使って確認してください。読み取り用キーをクライアントに含めないでください。送信する予定のフィールドだけを記録してください。書き込み専用キーでも、機密データを安全に収集できるわけではありません。

ワークロードごとにキーを分ける

実稼働環境の取り込み、ステージング、スケジュールされたレポート、およびコーディング エージェントのセットアップには個別のキーを使用します。ワークロード固有のキーにより、ローテーションとインシデント対応が小さくなります。1 つのレポート キーを取り消しても、イベントの取り込みが中断されることはありません。

キーには、その所有者と目的にちなんで名前を付けます。キーの値自体を記録せずに、キーがデプロイされる場所、そのスコープ、および予想されるローテーション所有者を記録します。

安全に回転および取り消し

まず置換キーを作成し、それをワークロードにデプロイし、リクエストが成功したことを確認してから、以前のキーを取り消します。 次のキーをローテーションするときは、取り込みとクエリの両方の経路をテストしてください: read-and-write 鍵。

非公開のキーがコミット、ログ、スクリーンショット、プロンプト、公開クライアントのバンドルに含まれた場合は、漏えいしたものとして扱ってください。すぐに無効化して交換し、影響を受けるチームのテーブルとクエリ履歴を確認してください。公開クライアントに意図的に含めた ingest キーは書き込み専用のままですが、コピーした人は誰でもイベントを送信できます。悪用されている場合は無効化して交換してください。

続けて、 ログ API, クエリ API、そして 機密データに関するガイダンス.