---
title: "Create an API key"
method: POST
path: "/v2/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /v2/api-keys`

Create a new API key for the authenticated user.

- Choose `key_type: "USER"` for a personal key that authenticates as you, or
  `key_type: "SERVICE"` for an automated service account key. The field is required.
- For service keys, supply at least one space via the `organizations` array. The service
  account is granted membership in each specified space. Multiple organizations and multiple
  spaces per organization are supported.
- For `USER` keys, the key inherits the authenticated user's own permissions.
- You may only assign roles at or below your own privilege level. Attempting to
  assign a role higher than your own returns `422 Unprocessable Entity`.
- All roles default to minimum privilege when omitted: space roles default to `MEMBER`,
  organization roles default to `READ_ONLY`, and `account_role` defaults to `MEMBER`.

**Authorization:**
- **User keys:** The authenticated user may create personal keys for themselves.
- **Service keys:** Requires the `SERVICE_KEY_CREATE` permission in the target space (space
  member or above).

The full API key value (`key`) is **only returned once** in the creation response.
Store it securely — it cannot be retrieved again. Use the `redacted_key` field on
subsequent reads.

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Request body

- union — Request body for creating an API key. Set `key_type` to select the kind of key: - `USER` — authenticates as the creating user, inheriting their current permissions. - `SERVICE` — authenticates as a service account: a dedicated, automatically provisioned identity with roles explicitly configured in the spaces you specify. Use this for automation, CI/CD pipelines, or any workload that should run independently of a specific user.
  - object
    - `key_type` 'USER', required — Must be `"USER"`.
    - `name` string, required — User-defined name for the API key.
    - `description` string — Optional user-defined description for the API key.
    - `expires_at` string, date-time — Optional expiration timestamp. If omitted the key never expires.
  - object
    - `key_type` 'SERVICE', required — Must be `"SERVICE"`.
    - `name` string, required — User-defined name for the API key.
    - `description` string — Optional user-defined description for the API key.
    - `expires_at` string, date-time — Optional expiration timestamp. If omitted the key never expires.
    - `account_role` union — Strict request form of UserRoleAssignment. Used in write request bodies. - `PREDEFINED`: `{ "type": "PREDEFINED", "name": "ADMIN" | "MEMBER" | "ANNOTATOR" }` - `CUSTOM`: `{ "type": "CUSTOM", "id": "<encoded-role-id>" }`
      - PredefinedUserRoleAssignmentRequest — A predefined account-level role assignment in a write request (strict form of PredefinedUserRoleAssignment).
        - `type` 'PREDEFINED' | 'CUSTOM', required
        - `name` 'ADMIN' | 'MEMBER' | 'ANNOTATOR', required — Account-level role of the user. These are pre-defined roles in Arize.
      - CustomUserRoleAssignmentRequest — A custom RBAC role assignment in a write request (strict form of CustomUserRoleAssignment).
        - `type` 'PREDEFINED' | 'CUSTOM', required
        - `id` string, required — A universally unique identifier (base64-encoded opaque string).
    - `organizations` ServiceKeyOrgAssignment[], required — Organizations the service account should have access to. Each entry specifies an organization and the spaces within it. Must include at least one organization with at least one space. All spaces must belong to the organization they are listed under.
      - `org_id` string, required — ID of the organization to grant the service account access to.
      - `role` union — Strict request form of OrganizationRoleAssignment. Used in write request bodies. - `PREDEFINED`: `{ "type": "PREDEFINED", "name": "ADMIN" | "MEMBER" | "READ_ONLY" | "ANNOTATOR" }` - `CUSTOM`: `{ "type": "CUSTOM", "id": "<encoded-role-id>" }`
        - OrganizationPredefinedRoleAssignmentRequest — A predefined organization role assignment in a write request (strict form of OrganizationPredefinedRoleAssignment).
          - `type` 'PREDEFINED' | 'CUSTOM', required
          - `name` 'ADMIN' | 'MEMBER' | 'READ_ONLY' | 'ANNOTATOR', required — Organization-level role for the user. - `ADMIN`: Full access to the organization and its resources. - `MEMBER`: Standard access to the organization. - `READ_ONLY`: Read-only access to the organization. - `ANNOTATOR`: Limited access for annotation tasks only.
        - OrganizationCustomRoleAssignmentRequest — A custom RBAC role assignment in a write request (strict form of OrganizationCustomRoleAssignment).
          - `type` 'PREDEFINED' | 'CUSTOM', required
          - `id` string, required — A universally unique identifier (base64-encoded opaque string).
      - `spaces` ServiceKeySpaceAssignment[], required — Spaces within this organization the service account should have access to. Each entry specifies a space and optional role. All space IDs must belong to this organization.
        - `space_id` string, required — ID of the space to grant the service account access to.
        - `role` union — Strict request form of SpaceRoleAssignment. Used in write request bodies. - `PREDEFINED`: `{ "type": "PREDEFINED", "name": "ADMIN" | "MEMBER" | "READ_ONLY" | "ANNOTATOR" }` - `CUSTOM`: `{ "type": "CUSTOM", "id": "<encoded-role-id>" }`
          - PredefinedRoleAssignmentRequest — A predefined space role assignment in a write request (strict form of PredefinedRoleAssignment).
            - `type` 'PREDEFINED' | 'CUSTOM', required
            - `name` 'ADMIN' | 'MEMBER' | 'READ_ONLY' | 'ANNOTATOR', required — Space-level role for the user. - `ADMIN`: Full access to the space and its resources. - `MEMBER`: Standard access to the space. - `READ_ONLY`: Read-only access to the space. - `ANNOTATOR`: Limited access for annotation tasks only.
          - CustomRoleAssignmentRequest — A custom RBAC role assignment in a write request (strict form of CustomRoleAssignment).
            - `type` 'PREDEFINED' | 'CUSTOM', required
            - `id` string, required — A universally unique identifier (base64-encoded opaque string).

## Response `201`

API key successfully created or refreshed. The raw key is only returned once.

- union — Response for a newly created or refreshed API key. The `key_type` field discriminates the variant: - `USER` — standard user key; no bot user. - `SERVICE` — service key tied to a service account; includes a `bot_user` with the service account's resolved role assignments.
  - UserApiKeyCreated
    - `id` string, required — Unique identifier for the API key.
    - `name` string, required — User-defined name for the API key.
    - `description` string — Optional user-defined description for the API key.
    - `key_type` 'USER', required — Discriminator value for user keys.
    - `status` 'ACTIVE' | 'REVOKED', required — Current status of the API key. - ACTIVE - The key is valid for use. - REVOKED - The key has been revoked and is no longer valid.
    - `redacted_key` string, required — Redacted version of the key suitable for display (e.g., "ak-abc...xyz").
    - `created_at` string, date-time, required — Timestamp when the key was created.
    - `expires_at` string, date-time — Optional timestamp when the key will expire.
    - `created_by_user_id` string, required — ID of the user who created the key.
    - `last_used_at` string, date-time — Approximate timestamp when the key was last used for authentication. This value is periodically updated and may not reflect the most recent usage.
    - `key` string, required — The full API key value. **Only returned once** at creation or refresh time. Store it securely — it cannot be retrieved again.
  - ServiceApiKeyCreated
    - `id` string, required — Unique identifier for the API key.
    - `name` string, required — User-defined name for the API key.
    - `description` string — Optional user-defined description for the API key.
    - `key_type` 'SERVICE', required — Discriminator value for service keys.
    - `status` 'ACTIVE' | 'REVOKED', required — Current status of the API key. - ACTIVE - The key is valid for use. - REVOKED - The key has been revoked and is no longer valid.
    - `redacted_key` string, required — Redacted version of the key suitable for display (e.g., "ak-abc...xyz").
    - `created_at` string, date-time, required — Timestamp when the key was created.
    - `expires_at` string, date-time — Optional timestamp when the key will expire.
    - `created_by_user_id` string, required — ID of the user who created the key.
    - `last_used_at` string, date-time — Approximate timestamp when the key was last used for authentication. This value is periodically updated and may not reflect the most recent usage.
    - `key` string, required — The full API key value. **Only returned once** at creation or refresh time. Store it securely — it cannot be retrieved again.
    - `bot_user` ServiceKeyBotUser, required
      - `id` string, required — Global ID of the bot user.
      - `name` string, required — Display name of the bot user.
      - `account_role` union, required — An account-level role assignment. Discriminated by `type`: - `PREDEFINED`: one of the predefined roles (`admin`, `member`, `annotator`) - `CUSTOM`: a custom RBAC role identified by its ID Note: `CUSTOM` role assignments are not yet supported and are reserved for future use.
        - PredefinedUserRoleAssignment — A predefined account-level role assignment.
          - `type` 'PREDEFINED' | 'CUSTOM', required
          - `name` 'ADMIN' | 'MEMBER' | 'ANNOTATOR', required — Account-level role of the user. These are pre-defined roles in Arize.
        - CustomUserRoleAssignment — A custom RBAC role assignment.
          - `type` 'PREDEFINED' | 'CUSTOM', required
          - `id` string, required — A universally unique identifier (base64-encoded opaque string).
          - `name` string — Human-readable name of the custom role. Returned in responses only; ignored on input.
      - `organizations` ServiceKeyBotUserOrgAssignment[], required — Organization access assignments for the service account, each containing nested space assignments.
        - `org_id` string, required — ID of the organization the service account has access to.
        - `role` union, required — A role assignment for an organization membership. Discriminated by `type`: - `PREDEFINED`: one of the predefined roles (`ADMIN`, `MEMBER`, `READ_ONLY`, `ANNOTATOR`) - `CUSTOM`: a custom RBAC role identified by its ID
          - OrganizationPredefinedRoleAssignment — A predefined organization role assignment.
            - `type` 'PREDEFINED' | 'CUSTOM', required
            - `name` 'ADMIN' | 'MEMBER' | 'READ_ONLY' | 'ANNOTATOR', required — Organization-level role for the user. - `ADMIN`: Full access to the organization and its resources. - `MEMBER`: Standard access to the organization. - `READ_ONLY`: Read-only access to the organization. - `ANNOTATOR`: Limited access for annotation tasks only.
          - OrganizationCustomRoleAssignment — A custom RBAC role assignment.
            - `type` 'PREDEFINED' | 'CUSTOM', required
            - `id` string, required — A universally unique identifier (base64-encoded opaque string).
            - `name` string — Human-readable name of the custom role. Returned in responses only; ignored on input.
        - `spaces` ServiceKeyBotUserSpaceAssignment[], required — Space assignments within this organization. Roles are always present in the response (defaults are resolved server-side).
          - `space_id` string, required — ID of the space the service account has access to.
          - `role` union, required — Specifies which role to assign within a space. Discriminated by `type`: - `PREDEFINED`: a built-in platform role — `{ "type": "PREDEFINED", "name": "ADMIN" | "MEMBER" | "READ_ONLY" | "ANNOTATOR" }` - `CUSTOM`: a custom RBAC role identified by its ID — `{ "type": "CUSTOM", "id": "<encoded-role-id>" }` Used wherever a space-level role assignment is required (memberships, service key bindings, etc.).
            - PredefinedRoleAssignment — A predefined space role assignment.
              - …
            - CustomRoleAssignment — A custom RBAC role assignment.
              - …

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)