---
title: "Create a user"
method: POST
path: "/v2/users"
tags: ["Users"]
---

# Create a user

`POST /v2/users`

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>

## Request body

- CreateUserRequest
  - `name` string, required — Full name of the new user
  - `email` string, email, required — An email address
  - `role` union, required — 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).
  - `invite_mode` 'NONE' | 'EMAIL_LINK' | 'TEMPORARY_PASSWORD', required — 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 `CreateUserResponse.temporary_password` for security guidance.
  - `is_developer` boolean — Whether the user should have developer permissions (can use the Arize API). Defaults to `true` for `ADMIN` and `MEMBER` roles, and `false` for `ANNOTATOR`.

## Response `200`

An account user object

- User — An account user represents a member of the account. Users can be listed, updated, or removed from the account.
  - `id` string, required — A universally unique identifier (base64-encoded opaque string).
  - `name` string, required — Display name of the user
  - `email` string, email, required — An email address
  - `created_at` string, date-time, required — Timestamp for when the user was created
  - `status` 'ACTIVE' | 'INVITED' | 'EXPIRED', required — 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.
  - `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.
  - `is_developer` boolean, required — Whether the user has developer permissions (can use the Arize API)

## Other responses

- `201` — User created successfully
- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `409` — Resource conflict
- `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/revisions/2ce448f1de13/schema)