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

ant CLIの認証方法を選ぶ

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

ブラウザログインで発行されるトークンは、1つのワークスペースに紐づきます。環境ごとにワークスペースを分けている組織では、「いまどの認証情報でどのワークスペースに向いているか」を把握できているかが取り違えの防止に直結します。

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"

org:adminのトークンを日常操作用のプロファイルと混ぜると、通常のコマンドが強い権限で動きます。専用プロファイルに分けておけば、--profile adminを付けた操作だけが強い権限になります。

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

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

--profileはadmin専用のオプションではなく、どのプロファイルに対しても使えます。トークンが期限切れまたは期限間近なら、更新してから出力します。curlのようなHTTPクライアントを使うスクリプトで、保存済みのログイン情報を静的なAPIキーの代わりに使えます。

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 256,
       "messages": [{"role": "user", "content": "hi"}]}'

OAuthのアクセストークンはAuthorizationヘッダーに入れます。x-api-keyヘッダーは静的なAPIキー専用です。

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という特別な値はここでは使えません。

特定のワークスペース向けに作ったキーなら、そのワークスペースでしか使えず、ワークスペースIDの指定も要りません。ワークスペースIDは、Claude Consoleの設定にあるWorkspaces画面のID列で確かめられます。

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

認証情報はどの順で選ばれるか

環境変数・プロファイル・ログイン情報が同時に残っていると、どれが使われるかは優先順位で決まります。SDKの解決順を示す公式の表(コード内で渡す引数が最優先)のうち、CLIの環境に関わるのは次の4段階です。上から順に見て、最初に認証情報が見つかったものが勝ちます。

空文字の環境変数にも注意が要ります。ANTHROPIC_API_KEY=""のように空でexportしても、優先順位の1番目の枠は埋まったままです。空のキーでAPIキー経路が選ばれ、後ろの段階には落ちません。使わない変数は空にせずunsetします。

プロファイルが読み込まれたあとの環境変数は、プロファイルに書かれていない項目を補うだけです。ANTHROPIC_WORKSPACE_IDは、アクティブなプロファイルにworkspace_idがないときにだけ効きます。

認証状態を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を実行します。

ステージング用とプロダクション用のワークスペースIDをそれぞれ別プロファイルに割り当てておけば、--profile stagingか--profile productionを切り替えるだけで実行対象を誤りにくくなります。

設定ディレクトリとファイルの中身

プロファイルは設定ディレクトリの下に、2種類のファイルとして保存されます。ディレクトリは$ANTHROPIC_CONFIG_DIR、なければLinuxとmacOSで~/.config/anthropic、Windowsで%APPDATA%\Anthropicの順に決まります。アクティブなプロファイル名は$ANTHROPIC_PROFILE、active_configの中身、defaultの順で決まります。

認証情報のファイルだけを秘匿対象にすればよく、プロファイル設定のほうはイメージに焼き込んで環境を切り替えられます。この仕組みはClaude CodeやClaude Agent SDKにも共通で、フェデレーション用のプロファイルを1つ作れば、これらのツールの認証にも使えます。

つまずきやすいポイント

• ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENはプロファイルより優先される。プロファイルを切り替えたのに挙動が変わらないときは、まずこの2つが残っていないかを疑う
• workspace_idを書き換えただけでは既存トークンは更新されない。ワークスペースを変えるたびに再ログインが必要
• サービスアカウントキーのような複数ワークスペース対応のAPIキーでは、--workspace-idかANTHROPIC_WORKSPACE_IDを明示しないとどのワークスペースで実行されるか曖昧になる
• ant auth logoutとant auth logout --allの範囲を混同する。前者はアクティブなプロファイル1つだけを消すため、ほかのプロファイルの認証情報は残る
• 空文字の環境変数が優先枠を占める。ANTHROPIC_API_KEY=""のままだとログイン情報に落ちないので、unsetで消す

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

まとめ

ant CLIの認証は、個人開発のant auth login、管理操作のorg:adminスコープ、既存運用に寄せるANTHROPIC_API_KEY、非対話環境向けのWorkload Identity Federationの4系統です。複数ワークスペースを扱うならプロファイルを使い分けます。切り替えの前後ではant auth statusの(active)行を見て、いま有効な認証情報とワークスペースが想定どおりかを確かめます。コマンドの基本構造や出力フォーマットはant CLIの使い方にまとめています。