メインコンテンツまでスキップ
Markdown で見る

トークンの管理

Takumi Guard には2種類のトークンがあります。いずれも npm・PyPI の全パッケージマネージャーで共通して利用でき、設定方法も同じです。セットアップコマンドは npm / PyPI / RubyGems の各クイックスタートを参照してください。

トークンプレフィックス発行方法用途
メール認証トークンtg_anon_メール登録個人の開発環境（Shisho Cloud アカウント不要）
組織ユーザートークンtg_org_コンソールまたは Guard API組織全体のインストール追跡

メール認証トークン​

以下のエンドポイントはメール認証トークンに適用されます。認証が必要なリクエストにはすべて Authorization: Bearer <APIキー> を使用します。

メールアドレスの登録​

メールアドレスを登録すると、メール認証トークンが発行されます。

curl -X POST https://npm.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "ja"}'

language フィールドは省略可能で、デフォルトは "en"（英語）です。"ja" を指定すると、すべてのメールが日本語で届きます。

API キーはウェルカムメールに直接記載されているため、確認用リンクをクリックする必要はありません。

トークンステータスの確認​

curl -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens/status

最終使用日時を含む利用統計情報が返されます。

トークンの確認方法​

API キーは登録時に届くウェルカムメールに記載されています。また、パッケージマネージャーは認証情報を平文の設定ファイルに保存するため、セットアップ時に保存された場所からトークンを復元することもできます。

note

パッケージマネージャーは平文の認証情報のみをサポートしています。これは各パッケージマネージャーの認証プロトコルの制約であり、Takumi Guard の設計上の選択ではありません。

npm​

トークンは .npmrc（プロジェクトレベルまたはユーザーレベルの ~/.npmrc）に保存されています。

cat ~/.npmrc | grep flatt.tech
# 出力: //npm.flatt.tech/:_authToken=tg_anon_xxxxxx

yarn berry（v2+）の場合は .yarnrc.yml を確認してください。

grep npmAuthToken .yarnrc.yml

bun の場合は bunfig.toml を確認してください。

grep token bunfig.toml

pip / uv​

pip config set で設定した場合（推奨）は、以下のコマンドで保存された値を確認できます。

pip config get global.index-url
# 出力: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

uv の場合は環境変数を確認してください。

echo $UV_INDEX_URL
# 出力: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

環境変数で設定した場合は、シェルプロファイル（.bashrc、.zshrc など）を確認してください。

echo $PIP_INDEX_URL
# 出力: https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

uv.toml（ユーザーレベル: ~/.config/uv/uv.toml、プロジェクトレベル: uv.toml または pyproject.toml）で設定した場合は以下を確認してください。

grep -r flatt.tech ~/.config/uv/uv.toml uv.toml pyproject.toml 2>/dev/null

Poetry​

poetry config http-basic.takumi-guard
# 出力: Username: token, Password: tg_anon_xxxxxx

トークンのローテーション​

現在のキーがある場合：regenerate エンドポイントを使ってすぐにローテーションできます。

curl -X POST \
  -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens/regenerate

レスポンスに新しいキーが含まれています。古いキーは即座に無効化されます。古いキーを使用しているすべてのパッケージマネージャーの設定を更新してください。

  • npm: .npmrc を更新（//npm.flatt.tech/:_authToken=<新しいキー>）
  • pip: pip config set global.index-url https://token:<新しいキー>@pypi.flatt.tech/simple/ を再実行（環境変数を使用している場合は PIP_INDEX_URL を更新）
  • uv: シェルプロファイルの UV_INDEX_URL を更新
  • poetry: poetry config http-basic.takumi-guard token <新しいキー> を実行

キーを紛失した場合：まずパッケージマネージャーの設定からの復元をお試しください。どこにも見つからない場合は、同じメールアドレスで再登録してください。

curl -X POST https://npm.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "ja"}'

メールアドレスがすでに確認済みのため、既存トークンの確認方法、追加エコシステムのセットアップコマンド、およびワンタイムリセットコードを含むメールが送信されます。メールにはメールアドレスとリセットコードが埋め込まれた、そのままコピーして実行できるコマンドが記載されています。

curl --json '{"email": "you@example.com", "code": "XXXX"}' \
  https://npm.flatt.tech/api/v1/tokens/reset

リセットコードの有効期限は 1 時間です。レスポンスに新しいキーが含まれ、古いキーは即座に無効化されます。コードの有効期限が切れた場合は、再度登録リクエストを送信すれば新しいコードが届きます。この操作はいつでも繰り返し実行できます。

info

メールアドレスは npm.flatt.tech と pypi.flatt.tech のどちらに送信しても構いません。両者は同じトークンデータベースを共有しているため、どちらのエンドポイントを使用しても、取得したトークンはすべてのエコシステムで利用可能です。

トークンの失効​

curl -X DELETE \
  -H "Authorization: Bearer tg_anon_xxxxxx" \
  https://npm.flatt.tech/api/v1/tokens

トークンは即座に無効化されます。

警告

失効後、無効化されたトークンを使ったコマンドはすべてのエコシステムで 401 エラーで失敗します。失効前に .npmrc、環境変数、poetry の設定を更新してください。

組織ユーザートークン​

有料機能

この機能を利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは料金と請求を参照してください。

組織ユーザートークンを使うと、組織内のメンバーによるパッケージのインストール状況をインストールログで確認できます。

トークンの利用場面​

組織ユーザートークンは、以下のような場面で活用できます。

  • チーム全体でインストールされたパッケージを一元的に把握したい
  • 開発者ごとのインストールを、ユーザー識別子を通じて追跡したい
GitHub Actions などからキーレスで利用する場合

GitHub Actions から Bot ID と OIDC を組み合わせて利用する場合、組織ユーザートークンの発行は不要です。ワークフロー実行ごとに短期トークンが自動的に発行・破棄され、長期シークレットを CI 環境に持たずに済みます。詳しくは npm GitHub Actions セットアップ、PyPI、RubyGems の各セクションを参照してください。

トークンの発行​

組織ユーザートークンは、コンソールの「トークン発行」ボタンから作成するか、ボットが Guard API を利用して発行できます。Guard API を用いたトークン発行の活用例は、管理ツールによる一括セットアップを参照してください。

ここでは Takumi / Shisho Cloud コンソールによるトークン発行について説明します。

  1. Takumi / Shisho Cloud コンソールで Guard > トークン に移動してください。

  2. トークン発行 をクリックしてください。以下のトークン一覧画面の右上にボタンがあります。

    Guard トークン画面

  3. 発行フォームが表示されます。

    トークン発行フォーム

  4. ユーザー識別子 を入力してください。4〜255 文字で、英数字、.、_、@、+、- が使用できます。

  5. 発行 をクリックしてトークンを生成してください。

ユーザー識別子 はトークンに付与されるラベルです。インストールログの各エントリに表示され、どの開発者がどのパッケージをインストールしたかを把握できます。組織内で一貫した命名規則を定めておくことを推奨します。

例値説明
メールアドレスalice@example.com個人を簡単に特定できる
社内ユーザー名alice社内ディレクトリと一致させやすい
デバイスのシリアルナンバー + OS ユーザー名C02X1234_jdoeデバイスとユーザーの組み合わせで識別できる
資産管理 ID + 社員 IDASSET0042_EMP12345組織で管理している ID を利用できる
警告

トークンは発行後に一度だけ表示されます。必ずすぐにコピーして安全な場所に保存してください。ダイアログを閉じると、トークンのシークレットは再取得できません。トークン一覧にはマスクされたプレフィックスのみ表示されます。

発行戦略の設計指針

組織ユーザートークンの発行粒度には、おおむね以下の 3 通りの戦略があります。

  • 人ごとに発行する（例：alice@example.com）。個人の特定が容易で、退職・異動時の管理がシンプル
  • 端末ごとに発行する（例：MacBook-C02X1234）。端末単位での突合が容易だが、複数端末を持つ場合に枠が増えやすい
  • 端末内のユーザーごとに発行する（例：C02X1234_alice）。端末 × ユーザーで一意になり、共用端末や複数アカウント環境で有効

どの粒度を選ぶかは、(1) インストールログから「誰が・どの端末で」を特定したい解像度と、(2) EDR や資産管理など、既存テレメトリとの突合のしやすさで設計するのがおすすめです。たとえば EDR が端末シリアル単位でログを残しているなら、トークンのユーザー識別子にも同じシリアルを含めておくと、後からの相互参照が容易になります。

組織ユーザートークンの失効​

組織ユーザートークンを失効させるには、Takumi / Shisho Cloud コンソールの Guard > トークン でトークン一覧から対象トークンの 失効 ボタンをクリックしてください。トークンは即座に無効になります。

失効後は、無効化されたトークンを使用しているパッケージマネージャーの設定を更新してください。

  • npm: .npmrc の //npm.flatt.tech/:_authToken を削除するか、新しいトークンに置き換えてください
  • pip: pip config set global.index-url を新しいトークンで再実行するか、デフォルトのインデックスに戻してください
  • uv: シェルプロファイルの UV_INDEX_URL を更新してください
  • poetry: poetry config http-basic.takumi-guard token <新しいトークン> を実行するか、ソースを削除してください

無効化されたトークンを使用したコマンドは、すべてのエコシステムで 401 エラーにより失敗します。

に最終更新