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

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

概要

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

今回追加した次の 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 など、用途に応じて組織ロールを使い分けてください。

利用例

有料機能

組織ユーザートークンを利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは料金と請求を参照してください。

1. Shisho Cloud のコンソールで 設定 → ボット → ボットを追加 からボットを作成し、用途に応じた組織ロール（organization/takumi_guard_token_issuer または organization/takumi_manager）を付与しましょう。

2. ボットに対して API キーを発行し、API キーとボット ID の両方 をお使いの自動化ツールのシークレットとして保存します。API に渡すクレデンシャルは、両者をコロン (:) で連結した shisho_apikey_…:BT01… の形式です。

3. 次のように呼び出すと、新しいトークンを発行できます。

   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 ドキュメントを参照してください。ユーザー識別子の命名例や失効方法など、運用上の詳細はトークンの管理を参照してください。