> ## 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 **ALPHA**. 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 scoped to a space. Service keys are backed by a dedicated bot user with configurable roles. When no roles are specified the server applies its defaults (`space_role=member`, `org_role=read-only`, `account_role=member`).

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

| Option            | Description                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `--name`, `-n`    | Name for the API key (max 256 characters) (required)                                                   |
| `--space`, `-s`   | Space name or ID the service key is scoped to (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 |
| `--space-role`    | Space role for the bot user: `admin`, `member`, or `read-only`                                         |
| `--org-role`      | Organization role for the bot user: `admin`, `member`, or `read-only`                                  |
| `--account-role`  | Account role for the bot user: `admin` or `member`                                                     |
| `--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}
# Service key scoped to a space (server-default roles)
ax api-keys create-service-key \
  --name "Staging Service Key" \
  --space sp_abc123

# Service key with explicit roles
ax api-keys create-service-key \
  --name "Read-Only Service Key" \
  --space sp_abc123 \
  --space-role read-only \
  --org-role read-only
```

## `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"
```