# メール認証トークンの管理 {#token-management}

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

:::info 1つのトークンで全エコシステムに対応
API キー（`tg_anon_…`）は、Takumi Guard の**すべて**のエコシステム（npm および PyPI）で利用できます。登録は一度だけで十分です。同じトークンで任意のパッケージマネージャーを設定できます。
:::

## トークンステータスの確認 {#token-status}

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

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

## トークンの確認方法 {#finding-token}

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

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

### npm {#finding-token-npm}

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

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

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

```bash
grep npmAuthToken .yarnrc.yml
```

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

```bash
grep token bunfig.toml
```

### pip / uv {#finding-token-pip}

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

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

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

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

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

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

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

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

### Poetry {#finding-token-poetry}

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

## トークンのローテーション {#rotating-token}

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

```bash
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 <新しいキー>` を実行

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

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

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

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

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

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

## トークンの失効 {#revoking-token}

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

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

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