arize-admin

Arize 管理スキル

Arize のユーザー、組織、スペース、ロール、権限、API キーをプログラムで管理します。これらはエンタープライズのアクセス制御を支える基本要素です。

必要な権限： ほとんどの操作には、org-admin または account-admin の権限が必要です。コマンドが 403 Forbidden を返す場合、認証済みプロファイルの権限が不足しています。

破壊的操作のルール： リソースを削除、失効、除去、または元に戻せない形で変更するコマンド（delete、revoke、remove-user、unrestrict）を実行するには、事前にユーザーから明示的な確認を得る必要があります。ユーザーからこれらの操作を依頼された場合：

1. 実行される内容を正確に要約します（例：「この操作により [email protected] のユーザーを削除し、そのユーザーの API キーを連鎖的に失効させ、組織／スペースのすべてのメンバーシップとロールの割り当てを解除します。」）。
2. ユーザーに確認を求めます（AskUserQuestion を使用します）。
3. ユーザーの確認後に限り、CLI の対話型プロンプトをスキップするため --force を付けてコマンドを実行します。

ユーザーに確認せず、--force を付けた破壊的なコマンドを実行してはいけません。

使用する場面

• アカウントにユーザーを招待し、組織やスペースに割り当てる
• 1 つのコマンドでユーザーのオフボーディングとすべてのアクセス権の失効を行う
• 新しいチームをオンボーディングする：スペースを作成し、カスタムロールを作成し、ユーザーを割り当て、サービスキーを生成する
• SAML/SSO 属性マッピング用のカスタムロールを作成する（安定したロール ID が必要です）
• 明示的にバインドされたユーザーのみがアクセスできるよう、プロジェクトを制限する
• CI/CD パイプラインやマルチテナントアーキテクチャ向けに、スコープを限定したサービスキーを作成する
• API キーをローテーションまたは失効させる
• スペース内にプロジェクトを作成または削除する

事前に確認する質問

複数ステップのワークフローでは、ax コマンドを実行する前に必要な情報をすべて収集します。ワークフローの途中で何度も確認することを避けるため、AskUserQuestion を使用します。先に最新のデータ（組織の一覧など）を取得し、ユーザーに ID を思い出してもらうのではなく、実際の選択肢を提示します。

新しいチームのオンボーディング

1. 組織名が分かっている場合は ax organizations get NAME -o json を実行します。組織名を選択肢として提示する場合は ax organizations list -o json を使用します。
2. AskUserQuestion を 1 回呼び出し、最大 4 つの質問で以下を確認します。
   • どの組織ですか？ — 一覧にある組織名を選択肢として提示します
   • スペース名 — 新しいチームのスペース名
   • チームメンバー — 招待するユーザーの名前とメールアドレス（ユーザーは「その他」を選択して入力できます。まだいない場合はその旨を確認します）
   • サービスキーは必要ですか？ — CI/CD パイプライン用のサービスキーを生成するかどうか

ユーザーのオフボーディング

コマンドを実行する前に確認します。

• どのユーザーですか？ — メールアドレス（その後、ax users get EMAIL -o json で検索します）

プロジェクトの制限

コマンドを実行する前に確認します。

• どのスペースとプロジェクトですか？ — プロジェクトのグローバル ID を検索するために必要です
• どのユーザーに明示的なアクセス権を付与しますか？ — 制限対象のプロジェクトにバインドするユーザーのメールアドレス

ユーザーの招待（単独）

コマンドを実行する前に確認します。

• 名前とメールアドレス — 招待する各ユーザーについて確認します
• ロール — ADMIN、MEMBER、ANNOTATOR（選択肢として提示します。アカウントレベルのユーザー作成には READ_ONLY ロールはありません）
• 招待モード — EMAIL_LINK、TEMPORARY_PASSWORD、NONE（--invite-mode は必須です）

API キーの失効またはローテーション

コマンドを実行する前に確認します。

• どのキーですか？ — ax api-keys list -o json を実行し、名前とステータスを選択肢として提示するか、KEY_ID を尋ねます
• 失効とローテーションのどちらですか？ — revoke は直ちに無効化します。refresh は同じスコープで新しいキーを発行し、--grace-period-seconds を指定しない限り、古いキーを直ちに無効化します

ユーザーが API キーを「削除」すると言った場合は、ax api-keys revoke を使用して無効化します。

概念

• Organization — アカウント内の名前付きグループです（例：事業部ごとに 1 つ）。Space は Organization 内にあります。ユーザーはまずアカウントに追加し、次に Organization、最後に Space に追加します。
• Space — トレース、データセット、プロジェクトを分離するワークスペースです。ユーザーをその Organization 内の Space に追加するには、先に Organization のメンバーである必要があります。
• Role — 権限の名前付きセットです。定義済みロールはシステムによって管理されます。カスタムロールは管理者が作成します。Organization／Space メンバーシップ用のロール（ADMIN、MEMBER、READ_ONLY、ANNOTATOR）は、ax role-bindings で使うカスタム RBAC ロールとは別です。
• Role binding — 特定のリソース（Space またはプロジェクト）上で、カスタムロールをユーザーに細かく割り当てます。
• Resource restriction — プロジェクトに制限を設定し、そのプロジェクトに明示的なロールバインディングを持つユーザーのみがアクセスできるようにします。より上位の階層レベル（Space、Organization、アカウント）で割り当てられたロールは対象外です。
• API key — user キー（作成者として認証し、ユーザーのすべての権限を持ちます）または service キー（特定の Space に範囲を限定し、自動化されたパイプライン向けです）のいずれかです。

前提条件

そのまま進め、必要な ax コマンドを実行してください。事前にバージョンやプロファイルを確認しないでください。

ax コマンドが失敗した場合：

• command not found またはバージョンエラー → references/ax-setup.md を参照してください
• 401 Unauthorized ／ API キーがない → ax profiles show を実行し、references/ax-profiles.md の手順に従ってください
• 403 Forbidden → アクティブなプロファイルに管理者権限がありません。references/ax-profiles.md を参照してください（管理者キーをチャットに貼り付けるようユーザーに求めないでください）
• セキュリティ： .env ファイルを読み取ったり、ファイルシステムから認証情報を検索したりしないでください。例外：シークレットではない ARIZE_SPACE_ID の行（Space を参照）。Arize の認証情報には ax profiles を使用してください。シークレットをチャットに貼り付けるようユーザーに求めないでください。生の API キー値を出力、記録、表示しないでください。認証情報がない場合は、references/ax-profiles.md を参照してください。

OAuth ログインのオプション： ユーザーは API キーの代わりに、ブラウザーを使った OAuth PKCE で認証できます。その場合は ax auth login を実行します（取り消すには ax auth logout を実行します）。アクティブなプロファイルは、ax profiles create --auth-method oauth で作成した OAuth プロファイルである必要があります。ユーザーから別の認証方法について質問された場合は、このオプションを案内してください。ブラウザーが対話的に開くため、ax auth login を自分で実行しないでください。

---

ユーザー

Organization または Space に追加する前に、ユーザーがアカウントに存在している必要があります。アカウントレベルのロール： ADMIN、MEMBER、ANNOTATOR

ax users list                                  # all users
ax users list --email "jane"                   # substring filter
ax users list --status ACTIVE                  # ACTIVE or INVITED
ax users list -l 100 -o json                   # paginate, get global IDs

ax users get USER_ID_OR_EMAIL                   # direct lookup; list is for browsing

ax users create \
  --full-name "Jane Doe" \
  --email [email protected] \
  --role MEMBER \
  --invite-mode EMAIL_LINK        # or: NONE | TEMPORARY_PASSWORD

ax users update USER_ID --full-name "Jane Smith"
ax users update USER_ID --is-developer          # grant developer flag

ax users delete --id USER_ID --force   # ⚠ confirm first — cascades: org/space memberships, API key revocation, role bindings
ax users delete --email [email protected] --force   # or resolve by email instead of ID

ax users resend-invitation USER_ID
ax users reset-password USER_ID

---

Organization

Organization のロール： ADMIN、MEMBER、READ_ONLY、ANNOTATOR

ax organizations list
ax organizations list --name "platform"
ax organizations list -l 100 -o json

ax organizations get "Platform Team"

ax organizations create --name "Platform Team" --description "Core ML platform"

ax organizations update "Platform Team" --name "ML Platform" --description "Updated"

# Add user (must exist in account first)
ax organizations add-user "Platform Team" --user-id USER_ID --role MEMBER

# Remove user (also removes from all child spaces) — ⚠ confirm first
ax organizations remove-user "Platform Team" --user-id USER_ID --force

# Delete organization: ⚠ irreversible; deletes org and all resources inside (spaces, projects, experiments, datasets)
ax organizations delete "Platform Team" --force

---

Space

Space のロール： ADMIN、MEMBER、READ_ONLY、ANNOTATOR

ax spaces list
ax spaces list --organization-id ORG_ID

ax spaces get "my-workspace"

# --organization-id required; get ORG_ID from ax organizations list -o json
ax spaces create --name "team-alpha" --organization-id ORG_ID

ax spaces update "team-alpha" --name "team-alpha-v2"

ax spaces delete "team-alpha" --force   # ⚠ confirm first — irreversible; deletes all resources

# User must be an org member before being added to a space
ax spaces add-user "team-alpha" --user-id USER_ID --role MEMBER
ax spaces remove-user "team-alpha" --user-id USER_ID --force   # ⚠ confirm first

---

ロール

ax role-bindings で使うカスタム RBAC ロールです。Organization／Space メンバーシップで使う、より単純な ADMIN／MEMBER／READ_ONLY／ANNOTATOR ロールとは別です。

ax roles list                          # all roles
ax roles list --is-custom -o json      # custom only — get stable IDs for SAML mappings
ax roles list --is-predefined

ax roles get "Data Scientist"          # inspect permissions

# --permissions is comma-separated; fully replaces on update
ax roles create \
  --name "Data Scientist" \
  --permissions "PROJECT_READ,DATASET_CREATE,EXPERIMENT_CREATE" \
  --description "Read traces, create datasets and experiments"

ax roles update "Data Scientist" --permissions "PROJECT_READ,DATASET_CREATE,EXPERIMENT_CREATE,EVALUATOR_CREATE"

ax roles delete "Data Scientist" --force   # ⚠ confirm first — predefined roles cannot be deleted

利用可能な権限の確認： システムロール（例：Member、Admin）に対して ax roles get <predefined-role> -o json を実行すると、有効な権限名を確認できます。

---

ロールバインディング

特定のリソース（Space またはプロジェクト）上で、カスタムロールをユーザーに細かく割り当てます。

# Assign at space level
ax role-bindings create \
  --user-id USER_GLOBAL_ID \
  --role-id ROLE_GLOBAL_ID \
  --resource-type SPACE \
  --resource-id SPACE_GLOBAL_ID

# Assign at project level
ax role-bindings create \
  --user-id USER_GLOBAL_ID \
  --role-id ROLE_GLOBAL_ID \
  --resource-type PROJECT \
  --resource-id PROJECT_GLOBAL_ID

ax role-bindings get BINDING_ID
ax role-bindings update BINDING_ID --role-id NEW_ROLE_ID
ax role-bindings delete BINDING_ID --force   # ⚠ confirm first

# List bindings for a resource type (--resource-type is required)
ax role-bindings list --resource-type SPACE
ax role-bindings list --resource-type PROJECT --user-id USER_GLOBAL_ID -o json

冪等です。対象リソースでユーザーに対するバインディングがすでに存在する場合、エラーなしで終了します。

---

リソース制限

プロジェクト、ダッシュボード、またはプロンプトに制限を設定し、そのリソースに明示的なロールバインディングを持つユーザーのみがアクセスできるようにします。Space／Organization レベルのロールは対象外です。

ax resource-restrictions list                                          # all restrictions, paginated
ax resource-restrictions list --resource-type DASHBOARD                # filter to one resource type (PROJECT, DASHBOARD, or PROMPT)
ax resource-restrictions list --limit 50 --cursor PAGINATION_CURSOR    # fetch next page

ax resource-restrictions restrict --resource-id RESOURCE_GLOBAL_ID     # idempotent
ax resource-restrictions unrestrict --resource-id RESOURCE_GLOBAL_ID --force   # ⚠ confirm first

# Finding a project ID
ax projects get NAME --space "my-workspace" -o json

---

API キー

範囲： ax api-keys list は、認証済みユーザーが所有するキーのみを返します。組織全体の監査には、Arize UI（Settings > API Keys）を使用してください。

ax api-keys list
ax api-keys list --key-type SERVICE --status ACTIVE -o json

# User key — authenticates as creator, inherits their full permissions
ax api-keys create --name "CI pipeline" --expires-at "2027-01-01T00:00:00"

# Service key — bot user scoped to org(s)/space(s) via --assignments JSON
# (recommended for CI/CD pipelines; get ORG_ID from `ax organizations list -o json`)
ax api-keys create-service-key \
  --name "team-alpha-traces" \
  --assignments '[{"org_id": "ORG_ID", "spaces": [{"space": "team-alpha"}]}]' \
  --expires-at "2027-01-01T00:00:00"

ax api-keys revoke KEY_ID --force   # ⚠ confirm first — invalidates the key immediately

# Rotation — issues a new key with same scope; old key dies immediately
# unless --grace-period-seconds keeps it valid while clients switch over
ax api-keys refresh KEY_ID --grace-period-seconds 3600
ax api-keys refresh KEY_ID --expires-at "2028-01-01T00:00:00"

生のキーが表示されるのは一度だけです。 すぐにシークレットマネージャーに保存してください。再取得することはできません。

create-service-key の範囲は --assignments で完全に指定します。割り当ての JSON 形式、ロールのデフォルト値、--account-role については、ax api-keys create-service-key --help を実行してください。--env-file PATH を渡すと、新しいキーを dotenv または .envrc ファイルの ARIZE_API_KEY に書き込み、会話ではなくファイルに保存できます。

---

プロジェクト

プロジェクトはスペース内にあり、トレース、データセット、実験が含まれます。

ax projects list --space SPACE
ax projects list --space SPACE --name "playground"   # substring filter
ax projects list --space SPACE -l 100 -o json        # get base64 IDs

ax projects get NAME_OR_ID --space SPACE

ax projects create --name "my-project" --space SPACE

ax projects update NAME_OR_ID --name "new-project-name" --space SPACE

ax projects delete NAME_OR_ID --space SPACE --force   # ⚠ confirm first — deletes all traces and datasets

注： プロジェクト ID（base64 文字列）は、ax spans export、ax traces export、ax resource-restrictions で使用します。コマンドでプロジェクト名が拒否された場合は、ax projects get NAME --space SPACE -o json の id フィールドを使用してください。ax projects list は一覧の確認用です。

---

エンタープライズのワークフローとトラブルシューティング

チームのオンボーディング、SAML/SSO のマッピング、プロジェクトの制限、オフボーディング、マルチテナントキーの手順と、トラブルシューティングの表は、references/REFERENCE.md にあります。

---

関連スキル

• arize-instrumentation：スペースの準備ができたら、LLM アプリでトレースを設定します。
• arize-trace：管理対象のスペース内でトレースをエクスポートして調査します。
• arize-dataset：スペース内でデータセットを作成、管理します。