> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Manage API keys with the AX CLI

<Note>
  The `ax api-keys` commands are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

The `ax api-keys` commands let you create and manage API keys for accessing the Arize platform programmatically.

## `ax api-keys list`

List API keys for the authenticated user.

```bash theme={null}
ax api-keys list [--key-type <type>] [--status <status>] [--limit <n>] [--cursor <cursor>]
```

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--key-type`      | Filter by key type: `USER` or `SERVICE`                        |
| `--status`        | Filter by status: `ACTIVE` or `REVOKED`                        |
| `--limit`, `-l`   | Maximum number of results to return (default: 15)              |
| `--cursor`, `-c`  | Pagination cursor for the next page                            |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs                                            |

**Examples:**

```bash theme={null}
ax api-keys list
ax api-keys list --key-type SERVICE --status ACTIVE
ax api-keys list --output api-keys.json
```

## `ax api-keys create`

Create a new user API key. The key authenticates as you with your full permissions. To create a space-scoped service key, use `create-service-key` instead.

```bash theme={null}
ax api-keys create --name <name> [options]
```

| Option            | Description                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `--name`, `-n`    | Name for the API key (max 256 characters) (required)                                                   |
| `--description`   | Optional description (max 1000 characters)                                                             |
| `--expires-at`    | Expiration datetime in ISO 8601 format (e.g. `2025-12-31T23:59:59`). If omitted, the key never expires |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                                         |
| `--verbose`, `-v` | Enable verbose logs                                                                                    |

<Warning>
  The raw key value is displayed once after creation. Save it securely — it will not be shown again.
</Warning>

**Examples:**

```bash theme={null}
# User key (no expiry)
ax api-keys create --name "CI Pipeline Key"

# User key with expiry
ax api-keys create \
  --name "Temporary Key" \
  --expires-at "2025-12-31T23:59:59"
```

## `ax api-keys create-service-key`

Create a new service API key with org and space assignments. Service keys are backed by a dedicated bot user scoped to one or more organizations, each containing one or more spaces. Assignments are supplied as a JSON array via `--assignments`. When no role is specified for a space or org, the server applies its defaults (`space=MEMBER`, `org=READ_ONLY`, `account=MEMBER`).

```bash theme={null}
ax api-keys create-service-key --name <name> --assignments <json> [options]
```

| Option                | Description                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`, `-n`        | Name for the API key (max 256 characters) (required)                                                                                    |
| `--assignments`, `-a` | JSON array (or path to a `.json` file) describing the org/space assignments for the service key's bot user (required). See format below |
| `--description`       | Optional description (max 1000 characters)                                                                                              |
| `--expires-at`        | Expiration datetime in ISO 8601 format (e.g. `2025-12-31T23:59:59`). If omitted, the key never expires                                  |
| `--account-role`      | Account-level role for the bot user: `ADMIN`, `MEMBER`, or `ANNOTATOR`. Defaults to `MEMBER` when omitted                               |
| `--output`, `-o`      | Output format (`table`, `json`, `csv`, `parquet`) or file path                                                                          |
| `--verbose`, `-v`     | Enable verbose logs                                                                                                                     |

**Assignments JSON format:**

Each entry describes an org and its spaces. `role` is optional at both levels (omit to use server defaults). Custom roles use `{"type": "CUSTOM", "id": "<role-id>"}`. Obtain org IDs with `ax organizations list --output json`.

```json theme={null}
[
  {
    "org_id": "<org-id>",
    "role": "READ_ONLY",
    "spaces": [
      {"space": "prod", "role": "MEMBER"},
      {"space": "staging"}
    ]
  }
]
```

<Warning>
  The raw key value is displayed once after creation. Save it securely — it will not be shown again.
</Warning>

**Examples:**

```bash theme={null}
# Service key with a single org and two spaces
ax api-keys create-service-key \
  --name "CI bot" \
  --assignments '[{"org_id":"T3Jn...","role":"READ_ONLY","spaces":[{"space":"prod","role":"MEMBER"},{"space":"staging"}]}]'

# Load assignments from a file
ax api-keys create-service-key \
  --name "CI bot" \
  --assignments ./assignments.json \
  --account-role MEMBER
```

## `ax api-keys revoke`

Revoke an API key. The key's status is set to revoked and it stops working immediately. This operation is irreversible. Revoking an already-revoked key is a no-op and still succeeds.

```bash theme={null}
ax api-keys revoke <key-id> [--force]
```

| Option            | Description                  |
| ----------------- | ---------------------------- |
| `--force`, `-f`   | Skip the confirmation prompt |
| `--verbose`, `-v` | Enable verbose logs          |

**Examples:**

```bash theme={null}
ax api-keys revoke key_abc123
ax api-keys revoke key_abc123 --force
```

## `ax api-keys refresh`

Atomically revoke an existing key and issue a replacement with the same name, description, type, and scope. Use this to rotate credentials without updating metadata.

```bash theme={null}
ax api-keys refresh <key-id> [--expires-at <datetime>] [--grace-period-seconds <n>]
```

| Option                   | Description                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--expires-at`           | New expiration datetime in ISO 8601 format. If omitted, the replacement key never expires                                           |
| `--grace-period-seconds` | Seconds the old key remains valid after refresh to allow clients to rotate. If omitted or 0, the old key is invalidated immediately |
| `--output`, `-o`         | Output format (`table`, `json`, `csv`, `parquet`) or file path                                                                      |
| `--verbose`, `-v`        | Enable verbose logs                                                                                                                 |

<Warning>
  The new raw key value is displayed once after refresh. Save it securely — it will not be shown again.
</Warning>

**Examples:**

```bash theme={null}
ax api-keys refresh key_abc123
ax api-keys refresh key_abc123 --expires-at "2026-12-31T23:59:59"
```