ant CLIの認証設定 — ワークスペース切り替えとプロファイル管理

ant CLIの認証方法を選ぶ

ant CLIは複数の認証手段に対応しています。個人利用ならant auth loginのブラウザログイン、CIやコンテナのような非対話環境ならWorkload Identity Federation、既存のAPIキー運用をそのまま使いたいなら環境変数、というのが基本の使い分けです。ant CLIのインストール方法では最短経路のant auth loginだけ紹介しましたが、本記事では組織運用に必要な選択肢を全部並べます。

どの手段を選んでも、最終的に発行されるトークンやAPIキーは特定のワークスペースに紐づきます。個人が複数プロジェクトを横断していたり、組織で環境ごとにワークスペースを分けていたりすると、「いまどの認証情報でどのワークスペースに向いているか」を把握できているかどうかが運用の安定性を左右します。

ant auth loginでOAuthログインする

ant auth loginは、ブラウザ経由のOAuthフローをClaude Consoleに対して開き、得られた認証情報を$ANTHROPIC_CONFIG_DIR配下に保存します。APIキーを自分で作って管理する必要がありません。

ant auth login

ブラウザを開けないリモートホストでは--no-browserを付けます。認可URLが表示されるので、認可後に返るコードを端末に貼り戻す流れです。

ant auth login --no-browser

ブラウザフローの途中で組織とワークスペースを選ぶ画面が出ます。発行されるトークンはそのワークスペースに紐づき、CLIはそのワークスペースに属するリソースしか見えません。ワークスペース選択の画面を省きたいときは--workspace-idを直接渡します。

ant auth login --workspace-id wrkspc_01...

--profileに渡した名前のプロファイルがまだ存在しない場合、ログイン完了時にその名前で新しいプロファイルが自動的に作られます。事前にant profileで空の器を用意しておく必要はありません。

対話的なログインはローカル開発向けです。CI・サーバー・コンテナのような非対話ワークロードにはWorkload Identity Federationを使います。トークン交換のAPI仕様・環境変数・エラーコードの詳細はWIFリファレンスにまとめています。

ログインした認証情報はcredentials/<profile>.jsonに書き込まれ、そのプロファイルへの初回ログイン時にはconfigs/<profile>.jsonも作られてアクティブなプロファイルになります。保存済みの認証情報を消すには次のコマンドです。

ant auth logout
ant auth logout --all

前者はアクティブなプロファイル1つだけを、後者は保存済みの全プロファイルをまとめて消します。共有端末や退職者対応でまとめて認証情報を無効化したいときは--allを使います。

管理者権限が必要な操作にはorg:adminスコープを使う

ant auth loginが既定で発行するのはワークスペース単位のトークンです。Admin APIで扱うような組織全体のリソースを操作するには、専用プロファイルでorg:adminスコープを要求します。

ant auth login --profile admin --scope "org:admin"

Authorizationヘッダー用のベアラートークンをそのまま欲しい場合は、次のコマンドで出力できます。

ant auth print-credentials --profile admin --access-token

--profileはadmin専用のオプションではなく、どのプロファイルに対しても使えます。トークンの有効期限が近ければ自動で更新してから出力するため、シェルスクリプトの中で都度呼び出しても失効したトークンを渡してしまう心配がありません。

APIキー環境変数で認証する

ANTHROPIC_API_KEY環境変数からもAPIキーを読み込みます。キーはClaude Consoleから取得します。

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

1回のコマンドだけキーを差し替えたいときは--api-keyフラグ、APIホストを変えたいときはANTHROPIC_BASE_URLか--base-urlを使います。個人用や特定ワークスペース専用ではなく複数ワークスペースにまたがるAPIキー(サービスアカウントキー等)を使う場合は、どのワークスペースで実行するかをANTHROPIC_WORKSPACE_ID環境変数か--workspace-idフラグで明示する必要があります。値はwrkspc_...形式のIDで、Workload Identity Federationのトークン交換でSDKが受け付けるdefaultという特別な値はここでは使えません。

サービスアカウントキーは、退職やローテーションのたびに個人の認証情報を作り直す必要がないという運用上の利点があります。反面、複数ワークスペースにまたがる分だけ「どのワークスペースで実行されたか」を毎回明示しないと事故につながりやすく、CIのジョブ定義ではANTHROPIC_WORKSPACE_IDを環境変数として固定しておくのが安全です。

ant messages create \
  --workspace-id wrkspc_01... \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

認証状態をant auth statusで確認する

ant auth statusは、どの認証情報が選ばれたか(APIキー環境変数・OAuthログイン・フェデレーション・プロファイル)、アクティブなプロファイル、そのトークンが紐づくワークスペース、設定ディレクトリのパスを表示します。想定と違うワークスペースにつながっているときの切り分けに使います。

ant auth status

Active profile:  default
Config dir:      ~/.config/anthropic
Profile config:  ~/.config/anthropic/configs/default.json
Credentials:     ~/.config/anthropic/credentials/default.json
 
Credentials
  (active) * Profile (user_oauth) [via active_config]       sk-ant-oat01-EXA...
 
Workspace
  (active) * Workspace                                      wrkspc_01... (Engineering)

(active)と付いた行が、実際に採用された認証情報とワークスペースです。このコマンドは状態を報告するだけでヘルスチェックはしないため、終了ステータスをスクリプトの分岐に使うのは避けます。想定と違うワークスペースに接続していると気づいたときに真っ先に見るべきコマンドで、認証周りのトラブルシュートの起点はほぼ常にここです。

複数ワークスペースを切り替える

対話ログインで発行されるトークンは1つのワークスペースに固定されます。複数のワークスペースにまたがって使うには、ワークスペースごとに名前付きプロファイルでログインし、切り替えます。個人の検証環境と本番のワークスペースを同じ端末から触るチームでは、この切り替えを誤ると検証のつもりが本番のリソースを操作してしまいます。プロファイル名をstaging・productionのように用途がひと目で分かる名前にしておくと、取り違えを防ぎやすくなります。

# 1. プロファイルを作る(対話ログイン。ブラウザで別のワークスペースを選ぶか
#    --workspace-idで選択画面を省く):
# ant auth login --profile other-ws
 
# 2. 以降のコマンドの既定プロファイルにする:
ant profile activate other-ws
 
# 3. またはデフォルトを変えずに1コマンドだけ切り替える:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

プロファイルを直接編集する

ant profileサブコマンドで、プロファイルの状態を直接確認・編集できます。

ant profile list
ant profile get --profile other-ws
ant profile set workspace_id wrkspc_01... --profile other-ws

ant profile setで書き換えられるキーはworkspace_id・base_url・organization_id・scope・client_id・console_urlの6つです。workspace_idを設定してもプロファイル設定ファイルに書き込まれるだけで、すでに発行済みの認証情報は再発行されません。新しいワークスペース向けのトークンを得るには、そのプロファイルであらためてant auth loginを実行します。

実務でよく組み合わせるのはworkspace_idとbase_urlです。ステージング用のワークスペースIDと本番用のワークスペースIDをそれぞれ別プロファイルに割り当てておけば、--profile stagingか--profile productionを切り替えるだけで実行対象を誤りにくくなります。

つまずきやすいポイント

• 環境変数がプロファイルより常に優先される。プロファイルを切り替えたのに挙動が変わらないときは、まずANTHROPIC_API_KEYが残っていないかを疑う
• workspace_idを書き換えただけでは既存トークンは更新されない。ワークスペースを変えるたびに再ログインが必要
• サービスアカウントキーのような複数ワークスペース対応のAPIキーでは、--workspace-idかANTHROPIC_WORKSPACE_IDを明示しないとどのワークスペースで実行されるか曖昧になる
• ant auth logoutとant auth logout --allの範囲を混同する。前者はアクティブなプロファイル1つだけを消すため、複数プロファイルを使っている環境では認証情報が意図せず残り続けることがある。端末を共有前に消し切ったつもりで確認を怠ると、次に使う人が前任者のワークスペースへそのままアクセスできてしまう

いずれも、ant CLIが「どの認証情報が最終的に勝つか」をant auth statusで確認する習慣で防げます。

まとめ

ant CLIの認証は、個人開発のant auth login、管理操作のorg:adminスコープ、既存運用に寄せるANTHROPIC_API_KEY、非対話環境向けのWorkload Identity Federationの4系統に整理できます。複数ワークスペースを扱うならプロファイルを使い分け、ant auth statusで常にどの認証情報が有効かを確認するのが安全です。どの手段を選んでも、最終的に確認すべき点は同じです。いま有効なのはどの認証情報で、どのワークスペースに向いているか、この2点です。コマンドの基本構造や出力フォーマットはant CLIの使い方にまとめています。