> ## 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.

# Create an API key

> Create a new API key for the authenticated user.

- `key_type` defaults to `user` when omitted.
- For `service` keys, `space_id` is required. The service key is
  scoped to the given space, and a bot user will be created with the specified roles.
- For `user` keys, `space_id` and `roles` must not be set — passing either returns `400`.
  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 `400 Bad Request`.
- All roles default to the minimum privilege when omitted: `space_role` → `member`,
  `org_role` → `read-only`, `account_role` → `member`.

**Authorization:**
- **User keys:** Requires the `developer` user permission flag. Returns `403` when this flag is absent.
- **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.

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




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/api-keys
openapi: 3.0.3
info:
  title: Arize REST API
  version: 2.0.0
  description: |
    API specification for the backend data server. The API is hosted globally
    at https://api.arize.com/v2 or in your own environment.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: eu-west-1a
        enum:
          - eu-west-1a
          - ca-central-1a
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
security:
  - bearerAuth: []
tags:
  - name: AI Integrations
    description: |
      AI integrations configure access to external LLM providers (e.g. OpenAI,
      Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
      entire account, a specific organization, or a specific space.
  - name: Annotation Configs
    description: >
      Annotation configs allow you to define consistent annotation schemas that

      can be reused across your workspace, ensuring evaluations are structured
      and

      comparable over time.
  - name: Annotation Queues
    description: >
      Annotation queues help you organize and manage human evaluation workflows.

      Use queues to assign spans or examples to annotators for review and
      labeling.
  - name: API Keys
    description: >
      API keys are used to authenticate requests to the Arize API. List your
      keys

      to view metadata; the raw secret is never returned after creation.
  - name: Datasets
    description: |
      Datasets are structured, version-controlled example collections you use to
      run, evaluate, and track LLM experiments.
  - name: Evaluators
    description: >
      Evaluators are reusable evaluation configurations used to assess the
      quality

      of LLM outputs. They can be template-based (using LLM judges) or
      code-based.
  - name: Experiments
    description: >
      Experiments let you systematically test prompt/model changes using
      datasets,

      tasks, and evaluators.
  - name: Integrations
    description: >
      Integrations configure access to external LLM providers (e.g. OpenAI,

      Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
      PagerDuty, Slack), and

      your own agents. Integrations can be scoped to the entire account, a
      specific

      organization, or a specific space.
  - name: Organizations
    description: >
      Organizations are top-level containers within an Arize AX account for
      grouping spaces.
  - name: Projects
    description: |
      Projects represent LLM applications being monitored in Arize where you can
      observe traces and spans.
  - name: Prompts
    description: >
      Prompts are reusable, versioned templates for LLM interactions. Use
      prompts

      to standardize and manage how you interact with LLMs across your
      application.
  - name: Resource Restrictions
    description: |
      Endpoints for restricting and unrestricting resources (projects, models).
  - name: Role Bindings
    description: |
      Role bindings assign a role to a user on a resource. REST currently
      supports space- and project-scoped bindings.
  - name: Roles
    description: >
      Roles define sets of permissions that can be assigned to users within an

      account. Create custom roles to tailor access control to your team's
      needs.
  - name: Spaces
    description: >
      Spaces are containers within an organization for grouping related
      projects,

      datasets, and experiments, enabling collaboration or isolated
      experimentation

      with role-based access control.
  - name: Spans
    description: |
      Spans represent individual operations within a trace. A span captures the
      timing, status, and attributes of a single operation in your application.
  - name: Tasks
    description: |
      Tasks are configurable units of work that tie one or more evaluators to a
      data source (project or dataset). Use tasks to automate evaluation of LLM
      outputs, with support for continuous evaluation and backfill runs.
  - name: Users
    description: >
      Users represent members of an account. The Users endpoints allow creating,

      listing, updating (display name), and removing users from the account
      programmatically.
paths:
  /v2/api-keys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: >
        Create a new API key for the authenticated user.


        - `key_type` defaults to `user` when omitted.

        - For `service` keys, `space_id` is required. The service key is
          scoped to the given space, and a bot user will be created with the specified roles.
        - For `user` keys, `space_id` and `roles` must not be set — passing
        either returns `400`.
          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 `400 Bad Request`.
        - All roles default to the minimum privilege when omitted: `space_role`
        → `member`,
          `org_role` → `read-only`, `account_role` → `member`.

        **Authorization:**

        - **User keys:** Requires the `developer` user permission flag. Returns
        `403` when this flag is absent.

        - **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.


        <Warning>This endpoint is in alpha, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>
      operationId: api_keys_create
      requestBody:
        $ref: '#/components/requestBodies/CreateApiKeyRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/ApiKeyCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  requestBodies:
    CreateApiKeyRequestBody:
      description: Body containing API key creation parameters
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiKeyCreate'
          examples:
            user_key_minimal:
              summary: User key (minimal)
              value:
                name: CI pipeline key
            user_key_with_expiry:
              summary: User key with expiry
              value:
                name: CI pipeline key
                description: Expires after one year.
                key_type: user
                expires_at: '2026-01-01T00:00:00Z'
            service_key_all_defaults:
              summary: Service key — all roles default to minimum privilege
              value:
                name: Ingestion bot
                key_type: service
                space_id: U3BhY2UxMjM
            service_key_explicit_roles:
              summary: Service key — explicit roles
              value:
                name: Ingestion bot
                key_type: service
                space_id: U3BhY2UxMjM
                roles:
                  space_role: member
                  org_role: read-only
                  account_role: member
  responses:
    ApiKeyCreated:
      description: >-
        API key successfully created or refreshed. The raw key is only returned
        once.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiKeyCreated'
          example:
            id: QXBp1001
            name: CI pipeline key
            key_type: user
            status: active
            key: ak-abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
            redacted_key: ak-abc...xyz
            created_by_user_id: Usr1001
            created_at: '2024-01-15T10:30:00Z'
            expires_at: '2025-01-15T10:30:00Z'
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 400
            title: Invalid request parameters
            detail: The 'name' field is required and must be a non-empty string.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
    Unauthorized:
      description: Authentication is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Authentication required
            detail: You must be authenticated to access this resource.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#authentication-required
    Forbidden:
      description: Insufficient permissions to access this resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Access forbidden
            detail: You do not have permission to access this resource.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 404
            title: Resource not found
            detail: The requested resource with ID '12345' was not found.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 422
            title: Unprocessable Entity
            detail: Minimum score must be less than maximum score.
            instance: /annotation-configs
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: |
            When throttled (429), how long to wait before retrying. Value is
            either a delta-seconds integer.
          schema:
            type: integer
            minimum: 0
          example: 42
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 429
            title: Rate limit exceeded
            detail: >-
              You have exceeded the allowed number of requests. Please try again
              later.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
  schemas:
    ApiKeyCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 256
          description: User-defined name for the API key.
          example: CI pipeline key
        description:
          type: string
          maxLength: 1000
          description: Optional user-defined description for the API key.
          example: Key used by the CI pipeline to upload evaluation results.
        key_type:
          allOf:
            - $ref: '#/components/schemas/ApiKeyType'
          default: user
          description: >
            Type of the API key to create. Defaults to `user`.

            - user - Key that authenticates as the creating user with their full
            permissions.
              `space_id` and `roles` must not be set (returns `400`).
            - service - Key scoped to a specific space backed by a dedicated bot
            user.
              Requires `space_id`. All roles default to minimum privilege when omitted.
          example: user
        expires_at:
          type: string
          format: date-time
          description: Optional expiration timestamp. If omitted the key never expires.
          example: '2026-01-01T00:00:00Z'
        space_id:
          type: string
          description: >
            ID of the space this service key is scoped to. Required when
            `key_type` is `service`;

            invalid for `user` keys (returns `400`).
          example: U3BhY2UxMjM
        roles:
          allOf:
            - $ref: '#/components/schemas/ApiKeyRoles'
          description: >
            Role assignments for the service key's bot user. Only valid when
            `key_type` is `service`;

            invalid for `user` keys (returns `400`). When omitted, each role
            field defaults to

            minimum privilege: `space_role` → `member`, `org_role` →
            `read-only`, `account_role` → `member`.
      additionalProperties: false
    ApiKeyCreated:
      allOf:
        - $ref: '#/components/schemas/ApiKey'
        - type: object
          required:
            - key
          properties:
            key:
              type: string
              description: >
                The full API key value. **Only returned once** at creation or
                refresh time.

                Store it securely — it cannot be retrieved again.
    Problem:
      type: object
      description: RFC 9457 Problem Details
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem
        type:
          type: string
          format: uri-reference
          description: A URI reference that identifies the problem type
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
      required:
        - title
        - status
      additionalProperties: false
    ApiKeyType:
      type: string
      enum:
        - user
        - service
      description: |
        Type of the API key.
        - user - Key associated with a specific user.
        - service - Key associated with a bot user for service authentication.
    ApiKeyRoles:
      type: object
      description: Role assignments for the bot user created with a service key.
      properties:
        space_role:
          allOf:
            - $ref: '#/components/schemas/ApiKeySpaceRole'
          default: member
          description: >
            Role to assign the bot user within the space. Defaults to `member`
            when omitted.

            Must be at or below the caller's own effective space role.
        org_role:
          allOf:
            - $ref: '#/components/schemas/ApiKeyOrganizationRole'
          default: read-only
          description: >
            Role to assign the bot user within the organization. Defaults to
            `read-only` when

            omitted. Must be at or below the caller's own organization role.
        account_role:
          allOf:
            - $ref: '#/components/schemas/ApiKeyAccountRole'
          default: member
          description: >
            Account-level role to assign the bot user. Defaults to `member` when
            omitted.

            Must be at or below the caller's own account role.
      additionalProperties: false
    ApiKey:
      type: object
      required:
        - id
        - name
        - key_type
        - status
        - redacted_key
        - created_at
        - created_by_user_id
      properties:
        id:
          type: string
          description: Unique identifier for the API key.
        name:
          type: string
          description: User-defined name for the API key.
        description:
          type: string
          description: Optional user-defined description for the API key.
        key_type:
          $ref: '#/components/schemas/ApiKeyType'
        status:
          $ref: '#/components/schemas/ApiKeyStatus'
        redacted_key:
          type: string
          description: >-
            Redacted version of the key suitable for display (e.g.,
            "ak-abc...xyz").
        created_at:
          type: string
          format: date-time
          description: Timestamp when the key was created.
        expires_at:
          type: string
          format: date-time
          description: Optional timestamp when the key will expire.
        created_by_user_id:
          type: string
          description: ID of the user who created the key.
        last_used_at:
          type: string
          format: date-time
          description: >-
            Approximate timestamp when the key was last used for authentication.
            This value is periodically updated and may not reflect the most
            recent usage.
      additionalProperties: false
    ApiKeySpaceRole:
      type: string
      enum:
        - admin
        - member
        - read-only
      description: |
        Space-level role for a service key's bot user.
        - admin - Full control within the space.
        - member - Standard space access.
        - read-only - View-only access.
    ApiKeyOrganizationRole:
      type: string
      enum:
        - admin
        - member
        - read-only
      description: |
        Organization-level role for a service key's bot user.
        - admin - Full control within the organization.
        - member - Standard organization access.
        - read-only - View-only access.
    ApiKeyAccountRole:
      type: string
      enum:
        - admin
        - member
      description: |
        Account-level role for a service key's bot user.
        - admin - Full account administrative access.
        - member - Standard account access.
    ApiKeyStatus:
      type: string
      enum:
        - active
        - revoked
      description: |
        Current status of the API key.
        - active - The key is valid for use.
        - revoked - The key has been revoked and is no longer valid.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api-key>
      description: >
        Most Arize AI endpoints require authentication. For those endpoints that
        require authentication, include your API key in the request header using
        the format

        ``` Authorization: Bearer <api-key>

        ```

````