> ## 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 Arize API keys programmatically. Create, list, revoke, and refresh user or service keys.

<Note>
  The `api_keys` client methods are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Manage Arize API keys programmatically. Create, list, revoke, and refresh user or service keys.

## Key Capabilities

* List API keys with optional filtering by type or status
* Create user keys (account-scoped) or service keys (space-scoped)
* Revoke keys immediately and permanently
* Refresh (rotate) a key while preserving its name and scope

## List API Keys

List API keys with cursor-based pagination. Optionally filter by `key_type` (`"USER"` or `"SERVICE"`), `status` (`"ACTIVE"` or `"REVOKED"`), `space` (name or ID — returns service keys for that space), and `user_id` (filter by creator for service keys, or view another user's keys as an account admin). When `status` is omitted, only active keys are returned.

```python theme={null}
resp = client.api_keys.list(
    key_type="SERVICE",                  # optional: "USER" or "SERVICE"
    status="ACTIVE",                     # optional: "ACTIVE" or "REVOKED"
    space="your-space-name-or-id",       # optional: filter service keys by space
    user_id="Usr1001",                   # optional: filter by creator (service) or user (user keys)
    limit=50,
)

for key in resp.api_keys:
    print(key.id, key.name, key.key_type)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/docs/api-clients/python/version-8/overview#response-objects).

## Create an API Key

Two key types are supported via separate methods:

* **User key** (`create`) — authenticates as the creating user with their full permissions.
* **Service key** (`create_service_key`) — backed by a dedicated bot user, scoped to one or more organizations and the spaces within them, with configurable roles.

<Warning>
  The raw key value is returned **only once** in the `key` field of the response. Store it securely — it cannot be retrieved again.
</Warning>

### User Key

```python theme={null}
result = client.api_keys.create(
    name="my-user-key",
    description="Used for CI pipeline",  # optional
)

print(result.key)   # store this securely — shown only once
print(result.id)
```

### Service Key

Service keys are tied to a dedicated service account scoped to one or more organizations, each containing one or more spaces (all spaces must belong to the same account). Pass `orgs` as a list of `OrgBinding` objects, each holding an `org_id`, at least one `SpaceBinding`, and an optional org-level `role`. When a role is omitted, the server applies the default predefined role (`MEMBER` for spaces, `READ_ONLY` for orgs, `MEMBER` for the account). All role assignments must be at or below the caller's own privilege level.

```python theme={null}
from datetime import datetime, timezone
from arize.api_keys.types import OrgBinding, SpaceBinding

result = client.api_keys.create_service_key(
    name="my-service-key",
    orgs=[
        OrgBinding(
            org_id="your-org-id",
            spaces=[SpaceBinding(space="your-space-name-or-id")],
        ),
    ],
    expires_at=datetime(2027, 1, 1, tzinfo=timezone.utc),  # optional
)

print(result.key)   # store this securely — shown only once
print(result.id)
```

To assign explicit roles, set the `role` field on each `SpaceBinding` / `OrgBinding` (and pass an `account_role` for the account level). Use `PredefinedRoleAssignment` / `OrganizationPredefinedRoleAssignment` for built-in roles (`ADMIN`, `MEMBER`, `READ_ONLY`) or `CustomRoleAssignment` / `OrganizationCustomRoleAssignment` for custom RBAC roles:

```python theme={null}
from arize.api_keys.types import (
    OrgBinding,
    SpaceBinding,
    PredefinedRoleAssignment,
    OrganizationPredefinedRoleAssignment,
)

result = client.api_keys.create_service_key(
    name="my-service-key",
    orgs=[
        OrgBinding(
            org_id="your-org-id",
            role=OrganizationPredefinedRoleAssignment(name="READ_ONLY"),
            spaces=[
                SpaceBinding(
                    space="your-space-name-or-id",
                    role=PredefinedRoleAssignment(name="MEMBER"),
                ),
            ],
        ),
    ],
)
```

## Revoke an API Key

Revoke a key by ID. The key's status is set to `REVOKED` and it is deactivated immediately and permanently. This operation is irreversible. Revoking an already-revoked key is a no-op and still succeeds.

```python theme={null}
client.api_keys.revoke(api_key_id="your-api-key-id")

print("API key revoked")
```

## Refresh an API Key

Revoke an existing key and issue a replacement with the same name, description, type, and scope. A new raw key value is returned. Use `grace_period_seconds` to keep the old key valid briefly while your services rotate to the new key.

<Warning>
  The new raw key value is returned **only once** in the `key` field of the response. Store it securely.
</Warning>

```python theme={null}
from datetime import datetime, timezone

result = client.api_keys.refresh(
    api_key_id="your-api-key-id",
    expires_at=datetime(2027, 1, 1, tzinfo=timezone.utc),  # optional
    grace_period_seconds=300,                               # optional: keep old key valid for 5 minutes
)

print(result.key)   # store this securely — shown only once
```