> ## 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 a user

> Create a new account user with explicit invite control.

**Invite modes**
- `none` — add the user directly with no invitation (for SSO-only accounts). The user
  is immediately active and can log in via the configured identity provider.
- `email_link` — create an `invited` invitation and send the user an email with a
  verification link to complete registration.
- `temporary_password` — create an `invited` invitation with a temporary password
  (returned once in the response). The user must reset it on first login.

**Idempotency on `email`** (applies when `invite_mode != "none"`)

| Existing state | Behavior | Response |
| --- | --- | --- |
| No prior invitation | Create a new `invited` invitation | `201 Created` |
| `invited` (not yet accepted) | Return the existing invitation as-is; do not resend | `200 OK` |
| `active` | Email belongs to an existing member | `409 Conflict` |
| `expired` | Create a new `invited` invitation | `201 Created` |
| `inactive` | User has been deactivated and cannot be re-invited | `409 Conflict` |

When `invite_mode` is `none` and the email already belongs to an active account member,
the request returns `409 Conflict`.

**Payload requirements**
- `name` — required, 1–255 characters
- `email` — required, must be a valid email address; used as the idempotency key
- `role` — required, one of `admin`, `member`, `annotator`; sets the account-level role
- `invite_mode` — required, one of `none`, `email_link`, `temporary_password`

Requires account admin role or USER_CREATE permission.

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




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/users
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/users:
    post:
      tags:
        - Users
      summary: Create a user
      description: >
        Create a new account user with explicit invite control.


        **Invite modes**

        - `none` — add the user directly with no invitation (for SSO-only
        accounts). The user
          is immediately active and can log in via the configured identity provider.
        - `email_link` — create an `invited` invitation and send the user an
        email with a
          verification link to complete registration.
        - `temporary_password` — create an `invited` invitation with a temporary
        password
          (returned once in the response). The user must reset it on first login.

        **Idempotency on `email`** (applies when `invite_mode != "none"`)


        | Existing state | Behavior | Response |

        | --- | --- | --- |

        | No prior invitation | Create a new `invited` invitation | `201
        Created` |

        | `invited` (not yet accepted) | Return the existing invitation as-is;
        do not resend | `200 OK` |

        | `active` | Email belongs to an existing member | `409 Conflict` |

        | `expired` | Create a new `invited` invitation | `201 Created` |

        | `inactive` | User has been deactivated and cannot be re-invited | `409
        Conflict` |


        When `invite_mode` is `none` and the email already belongs to an active
        account member,

        the request returns `409 Conflict`.


        **Payload requirements**

        - `name` — required, 1–255 characters

        - `email` — required, must be a valid email address; used as the
        idempotency key

        - `role` — required, one of `admin`, `member`, `annotator`; sets the
        account-level role

        - `invite_mode` — required, one of `none`, `email_link`,
        `temporary_password`


        Requires account admin role or USER_CREATE permission.


        <Note>This endpoint is in beta, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>
      operationId: users_create
      requestBody:
        $ref: '#/components/requestBodies/CreateUserRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/UserResponse'
        '201':
          $ref: '#/components/responses/UserCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  requestBodies:
    CreateUserRequestBody:
      description: Body containing user creation parameters and invite control.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateUserRequest'
          examples:
            predefined_email_link:
              summary: Invite a member via email link
              value:
                name: Jane Smith
                email: jane.smith@example.com
                role:
                  type: predefined
                  name: member
                invite_mode: email_link
            predefined_admin_sso:
              summary: Pre-provision an admin for SSO (no email sent)
              value:
                name: Alex Johnson
                email: alex.johnson@example.com
                role:
                  type: predefined
                  name: admin
                invite_mode: none
            predefined_annotator_temp_password:
              summary: Invite an annotator with a temporary password
              value:
                name: Sam Lee
                email: sam.lee@example.com
                role:
                  type: predefined
                  name: annotator
                invite_mode: temporary_password
  responses:
    UserResponse:
      description: An account user object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
          example:
            id: VXNlcjoxMjM0NQ==
            name: Jane Smith
            email: jane.smith@example.com
            created_at: '2024-01-01T12:00:00Z'
            status: active
            role:
              type: predefined
              name: member
            is_developer: true
    UserCreated:
      description: User created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserCreatedResponse'
          example:
            id: VXNlcjoxMjM0NQ==
            name: Jane Smith
            email: jane.smith@example.com
            role:
              type: predefined
              name: member
            status: invited
            is_developer: true
            invite_mode: email_link
            created_at: '2024-01-01T12:00: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
    Conflict:
      description: Resource conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 409
            title: Resource conflict
            detail: A resource with the given identifier already exists.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#resource-conflict
    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:
    CreateUserRequest:
      type: object
      required:
        - name
        - email
        - role
        - invite_mode
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Full name of the new user
        email:
          allOf:
            - $ref: '#/components/schemas/Email'
          description: Email address of the user to invite
        role:
          $ref: '#/components/schemas/UserRoleAssignment'
        invite_mode:
          allOf:
            - $ref: '#/components/schemas/InviteMode'
          description: Controls whether and how an invitation is sent
        is_developer:
          type: boolean
          description: >
            Whether the user should have developer permissions (can use the
            Arize API).

            Defaults to `true` for `admin` and `member` roles, and `false` for
            `annotator`.
      additionalProperties: false
    User:
      type: object
      required:
        - id
        - name
        - email
        - created_at
        - status
        - role
        - is_developer
      properties:
        id:
          $ref: '#/components/schemas/Id'
        name:
          type: string
          description: Display name of the user
        email:
          $ref: '#/components/schemas/Email'
        created_at:
          type: string
          format: date-time
          description: Timestamp for when the user was created
        status:
          $ref: '#/components/schemas/UserStatus'
        role:
          $ref: '#/components/schemas/UserRoleAssignment'
        is_developer:
          type: boolean
          description: Whether the user has developer permissions (can use the Arize API)
      description: |
        An account user represents a member of the account. Users can be listed,
        updated, or removed from the account.
      additionalProperties: false
    UserCreatedResponse:
      type: object
      required:
        - id
        - name
        - email
        - role
        - created_at
        - status
        - is_developer
        - invite_mode
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/Id'
          description: Unique identifier for the user
        name:
          type: string
          description: Full name of the user
        email:
          allOf:
            - $ref: '#/components/schemas/Email'
          description: Email address of the user
        role:
          $ref: '#/components/schemas/UserRoleAssignment'
        created_at:
          type: string
          format: date-time
          description: Timestamp for when the user was created
        status:
          $ref: '#/components/schemas/UserStatus'
        is_developer:
          type: boolean
          description: Whether the user has developer permissions (can use the Arize API)
        invite_mode:
          allOf:
            - $ref: '#/components/schemas/InviteMode'
          description: The invite mode used when the user was created.
        temporary_password:
          type: string
          format: password
          description: >
            Temporary password issued when `invite_mode` is
            `temporary_password`.

            Only present in the `POST /v2/users` 201 Created response.


            **Security notice:** this value is returned in the JSON response
            body

            (not out-of-band). Callers must treat it as a secret: avoid logging
            the

            full response, ensure transport is TLS-only, and instruct the user
            to

            change the password on first login.
      additionalProperties: false
    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
    Email:
      type: string
      format: email
      description: An email address
      example: user@example.com
    UserRoleAssignment:
      oneOf:
        - $ref: '#/components/schemas/PredefinedUserRoleAssignment'
        - $ref: '#/components/schemas/CustomUserRoleAssignment'
      discriminator:
        propertyName: type
        mapping:
          predefined:
            $ref: '#/components/schemas/PredefinedUserRoleAssignment'
          custom:
            $ref: '#/components/schemas/CustomUserRoleAssignment'
      description: >
        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.
    InviteMode:
      type: string
      enum:
        - none
        - email_link
        - temporary_password
      description: >
        Controls how the user is invited to the account.

        - `none` — add the user directly with no invitation email (for SSO-only
        accounts).

        - `email_link` — send the user an email with a verification link to
        complete registration.

        - `temporary_password` — issue a temporary password returned in the
        `POST /v2/users` response body; the user must reset it on first login.
        **Treat this value as a secret** — see
        `UserCreatedResponse.temporary_password` for security guidance.
    Id:
      type: string
      description: A universally unique identifier (base64-encoded opaque string).
      example: RW50aXR5OjEyMzQ1
    UserStatus:
      type: string
      enum:
        - active
        - invited
        - expired
      description: >
        Current status of the user in the account.

        - `active`: User has verified their email and can access the platform.

        - `invited`: User has been invited and their verification token is still
        valid.

        - `expired`: User was invited but their verification token has expired
        or is missing. A new invite is required.
    PredefinedUserRoleAssignment:
      type: object
      description: A predefined account-level role assignment.
      required:
        - type
        - name
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/UserRoleAssignmentType'
          default: predefined
          description: >-
            Discriminator identifying this as a predefined role assignment. Must
            be `predefined`.
        name:
          $ref: '#/components/schemas/UserRole'
      additionalProperties: false
    CustomUserRoleAssignment:
      type: object
      description: A custom RBAC role assignment.
      required:
        - type
        - id
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/UserRoleAssignmentType'
          default: custom
          description: >-
            Discriminator identifying this as a custom role assignment. Must be
            `custom`.
        id:
          allOf:
            - $ref: '#/components/schemas/Id'
          description: The unique identifier of the custom RBAC role.
        name:
          type: string
          readOnly: true
          description: |
            Human-readable name of the custom role.
            Returned in responses only; ignored on input.
      additionalProperties: false
    UserRoleAssignmentType:
      type: string
      enum:
        - predefined
        - custom
    UserRole:
      type: string
      enum:
        - admin
        - member
        - annotator
      description: Account-level role of the user. These are pre-defined roles in Arize.
  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>

        ```

````