---
title: "Add a user to an organization"
method: POST
path: "/v2/organizations/{org_id}/users"
tags: ["Organizations"]
---

# Add a user to an organization

`POST /v2/organizations/{org_id}/users`

Add a single existing account user to an organization with a specified role.

**Payload Requirements**
- `user_id` and `role` are both required.
- If the user is already a member, their role is updated to the specified value (upsert).

**Role constraints**
- Users with an `annotator` account role can only be assigned the `annotator` organization role.
- Users with a non-annotator account role cannot be assigned the `annotator` organization role.

Requires organization admin.

**Valid example**
```json
{
  "user_id": "VXNlcjo0MjphQmNE",
  "role": "MEMBER"
}
```

**Invalid example** (annotator account user assigned non-annotator org role — returns 400)
```json
{
  "user_id": "VXNlcjo0MjphQmNE",
  "role": "ADMIN"
}
```

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

## Path parameters

- `org_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

- AddOrganizationUserRequest
  - `user_id` string, required — A universally unique identifier (base64-encoded opaque string).
  - `role` union, required — 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).

## Response `200`

User successfully added to the organization

- OrganizationMembership
  - `id` string, required — A universally unique identifier (base64-encoded opaque string).
  - `user_id` string, required — A universally unique identifier (base64-encoded opaque string).
  - `organization_id` string, required — A universally unique identifier (base64-encoded opaque string).
  - `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.

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