arize-admin

Arize Admin Skill

Programmatic management of Arize users, organizations, spaces, roles, permissions, and API keys — the building blocks for enterprise access control.

Privilege requirement: Most operations require org-admin or account-admin privileges. If commands return 403 Forbidden, the authenticated profile lacks sufficient permissions.

Destructive-action rule: Commands that delete, revoke, remove, or irreversibly modify resources (delete, revoke, remove-user, unrestrict) require explicit user confirmation before execution. When a user asks you to perform one of these operations:

1. Summarize exactly what will happen (e.g., "This will delete user jane@example.com and cascade-revoke their API keys and remove all their org/space memberships and role bindings.")
2. Ask the user to confirm (use AskUserQuestion).
3. Only after the user confirms, run the command with --force to skip the CLI's interactive prompt.

Never run a --force destructive command without confirming with the user first.

When to Use

• Invite users to the account, assign them to orgs and spaces
• Offboard a user and revoke all their access in one command
• Onboard a new team: create a space, create a custom role, assign users, generate a service key
• Create custom roles for SAML/SSO attribute mappings (need stable role IDs)
• Restrict a project so only explicitly bound users can access it
• Create scoped service keys for CI/CD pipelines or multi-tenant architectures
• Rotate or revoke API keys
• Create or delete projects within a space

Upfront Questions

For multi-step workflows, collect all required information before running any ax commands. Use AskUserQuestion to avoid back-and-forth mid-workflow. Fetch live data first (e.g. org list) so you can present real options rather than asking the user to recall IDs.

Onboarding a new team

1. Run ax organizations list -o json to get available org names.
2. Use AskUserQuestion (single call, up to 4 questions) to gather:
   • Which org? — present the org names from the list as options
   • Space name — what to call the new team's space
   • Team members — names and emails to invite (user can type via "Other"; ask if none yet)
   • Service key? — whether to generate a service key for CI/CD pipelines

Offboarding a user

Ask before running any commands:

• Which user? — email address (then look up with ax users list --email)

Restricting a project

Ask before running any commands:

• Which space and project? — to look up the project global ID
• Which users get explicit access? — emails of users to bind to the restricted project

Inviting users (standalone)

Ask before running any commands:

• Name and email — for each user to invite
• Role — ADMIN, MEMBER, or ANNOTATOR (present as options; account-level user creation has no READ_ONLY role)
• Invite mode — EMAIL_LINK (default), TEMPORARY_PASSWORD, or NONE

Revoking or rotating an API key

Ask before running any commands:

• Which key? — run ax api-keys list -o json and present options by name and status; or ask for KEY_ID
• Revoke or rotate? — revoke invalidates immediately; refresh issues a new key with the same scope (zero-downtime rotation)

If the user says "delete" an API key, use ax api-keys revoke to invalidate it.

Concepts

• Organization — a named grouping within an account (e.g. one per business unit). Spaces live inside organizations. Users are added to the account first, then to orgs, then to spaces.
• Space — a workspace that isolates traces, datasets, and projects. A user must be an org member before they can be added to a space within that org.
• Role — a named set of permissions. Predefined roles are system-managed. Custom roles are created by admins. The roles for org/space membership (ADMIN, MEMBER, READ_ONLY, ANNOTATOR) are separate from custom RBAC roles used with ax role-bindings.
• Role binding — fine-grained assignment of a custom role to a user on a specific resource (a space or a project).
• Resource restriction — marks a project so that only users with an explicit role binding on that project can access it. Roles bound at any higher hierarchy level (space, org, account) are excluded.
• API key — either a user key (authenticates as the creator, full user permissions) or a service key (scoped to a specific space, for automated pipelines).

Prerequisites

Proceed directly — run the ax command you need. Do NOT check versions or profiles upfront.

If an ax command fails:

• command not found or version error → see references/ax-setup.md
• 401 Unauthorized / missing API key → run ax profiles show; follow references/ax-profiles.md
• 403 Forbidden → the active profile lacks admin privileges; see references/ax-profiles.md (never ask the user to paste an admin key into chat)
• Security: Never read .env files or search the filesystem for credentials. Use ax profiles for Arize credentials. Never ask the user to paste secrets into chat. Never echo, log, or display raw API key values. For missing credentials, see references/ax-profiles.md.

OAuth login option (v0.18.0+): Users can authenticate via browser-based OAuth PKCE instead of API keys by running ax auth login (then ax auth logout to revoke). Inform users of this option if they ask about authentication alternatives — do not run ax auth login yourself, as it opens a browser interactively.

Users

A user must exist in the account before they can be added to an org or space. Account-level roles: ADMIN, MEMBER, ANNOTATOR

ax users list                                  # all users
ax users list --email "jane"

Organizations

Organization roles: ADMIN, MEMBER, READ_ONLY, ANNOTATOR

Spaces

Space roles: ADMIN, MEMBER, READ_ONLY, ANNOTATOR

Roles

Custom RBAC roles used with ax role-bindings. Separate from the simpler ADMIN/MEMBER/READ_ONLY/ANNOTATOR roles in org/space membership.

Finding available permissions: Run ax roles get <predefined-role> -o json on a system role (e.g. Member, Admin) to see valid permission names.

Role Bindings

Fine-grained assignment of a custom role to a user on a specific resource (space or project).

Idempotent — if a binding already exists for the user on that resource, exits without error.

Resource Restrictions

Restricts a project or dashboard so only users with an explicit role binding on that resource can access it. Space/org-level roles are excluded.

API Keys

Scope: ax api-keys list returns only keys owned by the authenticated user. For org-wide auditing, use the Arize UI (Settings > API Keys).

The raw key is displayed once. Save it immediately in your secrets manager. It cannot be retrieved again.

create-service-key flags:

Scope create-service-key entirely through --assignments, not through separate --space/--space-role/--org-role flags.

Projects

Projects live inside spaces and contain traces, datasets, and experiments.

Note: Project IDs (base64 strings) are used by ax spans export, ax traces export, and ax resource-restrictions. If commands reject a project name, look up the id field from ax projects list -o json and use that instead.

Enterprise Workflows & Troubleshooting

Step-by-step workflows (onboard a team, SAML/SSO mappings, project restriction, offboarding, multi-tenant keys) and a troubleshooting table are in references/REFERENCE.md.

Related Skills

• arize-instrumentation: Set up tracing in an LLM app once a space is ready.
• arize-trace: Export and inspect traces within a managed space.
• arize-dataset: Create and manage datasets within a space.