# Takumi API に Guard 機能の操作エンドポイントを追加

Takumi Guard の **組織ユーザートークン**（`tg_org_`）を、Takumi API 経由で発行・一覧・取り消し・有効性確認できるようになりました。CI/CD パイプラインやオンボーディングスクリプト、MDM ツールといった自動化フローから、コンソールを経由せずトークンをプログラマブルに管理できます。

## 概要

コンソールからのトークン発行は[4 月のリリース](/docs/ja/r/202604-takumi-guard-org-user-token)で対応済みで、新規メンバーへの個別の払い出しといった都度の運用に向いています。一方、組織が拡大し、入退社時の発行・取り消しや漏洩時のクレデンシャル切り替えといった作業を仕組み化したくなると、コンソールではなくスクリプトから扱える経路が必要になります。

今回追加した次の 4 つのエンドポイントにより、トークンのライフサイクル全体を Takumi API から扱えるようになりました。

- `POST /o/{org_id}/guard/org-user-tokens` で任意の `user_identifier` を指定して新しいトークンを発行する
- `GET /o/{org_id}/guard/org-user-tokens` でトークンを一覧する（`user_identifier` のプレフィックスやステータスによる絞り込みに対応）
- `DELETE /o/{org_id}/guard/org-user-tokens/by-id/{token_id}` で管理 ID を指定してトークンを取り消す
- `POST /o/{org_id}/guard/org-user-tokens/probe` で平文のトークンがまだ有効かつ自組織のものかを確認する

いずれのエンドポイントも、標準の `Authorization: Bearer` ヘッダで認証します。指定する値はボットの **API キー** と **ボット ID** をコロン (`:`) で連結した文字列で、いずれも下の _利用例_ 手順 1 でボット作成時に取得できます。

```
Authorization: Bearer shisho_apikey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:BT01XXXXXXXXXXXXXXXXXXXXXXXX
```

必要な権限は、人間のユーザーが同じ操作をコンソールから行う場合と同じです。発行には **`organization/takumi_guard_token_issuer`**、取り消しには **`organization/takumi_manager`** など、用途に応じて組織ロールを使い分けてください。

## 利用例

:::info 有料機能
組織ユーザートークンを利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing)を参照してください。
:::

1. Shisho Cloud のコンソールで **設定 → ボット → ボットを追加** からボットを作成し、用途に応じた組織ロール（`organization/takumi_guard_token_issuer` または `organization/takumi_manager`）を付与しましょう。
2. ボットに対して API キーを発行し、**API キーとボット ID の両方** をお使いの自動化ツールのシークレットとして保存します。API に渡すクレデンシャルは、両者をコロン (`:`) で連結した `shisho_apikey_…:BT01…` の形式です。
3. 次のように呼び出すと、新しいトークンを発行できます。

   ```bash
   curl -sS https://api.cloud.shisho.dev/v1/o/$ORG/guard/org-user-tokens \
     -H "Authorization: Bearer $BOT_API_KEY:$BOT_ID" \
     --json '{"user_identifier": "alice-laptop"}'
   ```

## 詳細な API 仕様

ここまでの手順は、もっとも簡単な利用例の一つにすぎません。発行・一覧・取り消し・有効性確認の各エンドポイントは、お使いの自動化ツールや、既存のオンボーディング・退職処理に合わせて、自由に組み合わせて利用できます。

各エンドポイントのリクエスト・レスポンスの詳細スキーマやバリデーションルール、エラーレスポンスの形式については、[OpenAPI ドキュメント](https://api.cloud.shisho.dev/v1/docs/openapi.json)を参照してください。ユーザー識別子の命名例や失効方法など、運用上の詳細は[トークンの管理](/docs/ja/t/guard/features/token-management#user-tokens)を参照してください。