> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage users, seats, and roles

> List users, assign seats in bulk, set the seat assignment mode, change built-in and custom roles, add self-hosted users, and read audit logs with the CodeRabbit API.

Enterprise Plan (This feature is available exclusively as part of the Enterprise plan. Please refer to our pricing page for more information about our plans and features.)

Keep CodeRabbit seats and roles in sync with your directory, and pull audit logs into your security tooling.

## Before you start

* Your organization is on the Enterprise plan; see [Plans](https://docs.coderabbit.ai/api.md#plans). See [Authentication](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts) for the keys each operation accepts, including [workspace API tokens](https://docs.coderabbit.ai/api/workspace-api-tokens.md) for Enterprise SSO workspaces, and [Conventions](https://docs.coderabbit.ai/api/conventions.md) for base URLs, pagination, errors, and rate limits.
* The key owner has the access the task needs: the Admin role to manage seats, set the seat assignment mode, add users, and read audit logs; the `user_management:read` permission to list users; and `user_management:write` to change roles. See [Role-based access](https://docs.coderabbit.ai/management/roles.md).
* The curl examples read the key from `CODERABBIT_API_KEY`. The CLI examples use the [`coderabbit api` command](https://docs.coderabbit.ai/api/cli) with a key file.

Custom role definitions and the role lookup are product operations. Every other operation on this page is an export and user-management operation.

### Which credential does what

| Task | Enterprise SSO workspace | Any other organization |
| - | - | - |
| List users, read audit logs | Workspace API token | User key |
| Assign or unassign seats | Workspace API token, with the `members` body | User key |
| Change roles | Workspace API token, with `org_id` | User key |
| Look up role IDs, create and edit custom roles | Workspace API token, with a GitHub Cloud organization selected, or a user key from one of the workspace's GitHub Cloud organizations | User key |
| Set the seat assignment mode, add users | Not available | User key or instance key, self-hosted only |

In an SSO workspace, a workspace token covers every task that the API offers. For the general rules, see [Which key for which job](https://docs.coderabbit.ai/api/authentication.md#which-key-for-which-job).

## List users

1. Call [List all users in the organization](https://docs.coderabbit.ai/api/reference/list-users.md). To find who has a seat or a role, filter by seat status or by role.

   ```bash curl theme={null}
   curl --get "https://api.coderabbit.ai/v1/users" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "seat_filter=assigned" \
     --data-urlencode "limit=100"
   ```

   ```bash CLI theme={null}
   coderabbit api --api-key-file ~/.config/coderabbit/api-key request '/users?seat_filter=assigned&limit=100'
   ```

2. Read the response. `seats_purchased` and `seats_assigned` describe the subscription, and `seat_assignment_mode` shows whether seats are assigned automatically or manually. For each user, `user_id` is the Git provider's user ID, which the seat and role operations expect, and `role` is the user's role ID.

3. While `next_cursor` isn't `null`, request the next page with `cursor` set to that value and the same filters. See [Pagination](https://docs.coderabbit.ai/api/conventions.md#pagination).

The list includes only members of your organization by default. Set `membership=non_org` to list outside contributors, such as authors of pull requests on public repositories, or `membership=all` to list both.

With a workspace token and no `org_id`, the response has one row per person across the workspace, with each person's linked Git accounts. Add `org_id` to list a single organization of the workspace.

## Assign or unassign seats in bulk

> [!WARNING]
>
> In an Enterprise SSO workspace, use a workspace API token and the `members` body described in [Workspace tokens](#workspace-tokens-and-offboarding). The examples below use `action` and `user_ids`, which a workspace token rejects, and user and agentic keys reject `members`.

1. Collect the Git provider user IDs from `user_id` in the [user list](#list-users).

2. Call [Assign or unassign seats for multiple users](https://docs.coderabbit.ai/api/reference/manage-seats.md) with the `action` to take and the users' IDs in `user_ids`.

   ```bash curl theme={null}
   curl "https://api.coderabbit.ai/v1/users/seats" \
     --request POST \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"action": "assign", "user_ids": ["121358802", "22605247"]}'
   ```

   ```bash CLI theme={null}
   coderabbit api --api-key-file ~/.config/coderabbit/api-key request /users/seats --input seats.json
   ```

   The CLI reads the body from the file you pass with `--input` and sends a `POST`.

3. Check the result. A `200` response can still report failures for some users. `status` is `success`, `partial_success`, or `failure`, `succeeded` lists the processed IDs, and each `failed` entry has a `code`, such as `SEAT_NOT_AVAILABLE` when no seat is free.

Send large batches one after another rather than in parallel. For how seats are counted and released, see [Seat assignment](https://docs.coderabbit.ai/management/seat-assignment.md).

### Workspace tokens and offboarding

A workspace token sends a `members` array keyed by email, or by `cr_user_id` for a member without an email. [Manage seats and identities](https://docs.coderabbit.ai/management/sso/user-management-api.md#manage-seats-and-identities) shows the body.

A workspace token sets one seat per person for the whole workspace, not one per organization. CodeRabbit keeps the seat on the workspace member and applies it to every linked Git account, so one call changes the seat in all of the workspace's organizations. A Git account that isn't linked to a member keeps its own seat; find it in the workspace user list and send its `cr_user_id`.

To take a seat from a leaver, send `"seat_assigned": false` for the member. This works in Automatic mode too: the Automatic and Manual modes control who gets a seat when a pull request opens, and don't block an unassignment through the API. In Automatic mode, the person gets a seat again when one of their linked Git accounts opens a new pull request, as long as a seat is free.

If your identity provider provisions members through SCIM, remove the person there instead. SCIM deprovisioning removes the member, their linked Git identities, and their seat. See [SCIM](https://docs.coderabbit.ai/management/sso/scim.md).

## Set the seat assignment mode

In `automatic` mode, a person gets a seat when they open a new pull request, as long as a seat is available. In `manual` mode, admins assign seats. [Seat assignment](https://docs.coderabbit.ai/management/seat-assignment.md) describes both modes, including when CodeRabbit releases inactive seats.

The API changes the mode only for organizations on self-hosted CodeRabbit or on a self-managed Git provider. Other organizations get `403 SELF_HOSTED_ONLY` and change the mode in the app: an organization admin in **Team Management**, and an Enterprise SSO workspace admin in **Workspace Team Management**, as described in [Enterprise SSO workspaces](https://docs.coderabbit.ai/management/seat-assignment.md#enterprise-sso-workspaces).

1. Read the current mode from `seat_assignment_mode` in the [user list](#list-users).
2. Call [Update the seat assignment mode](https://docs.coderabbit.ai/api/reference/update-seat-assignment-mode.md) with `mode` set to `automatic` or `manual`.

   ```bash theme={null}
   curl "https://api.coderabbit.ai/v1/users/seats/assignment" \
     --request POST \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"mode": "manual"}'
   ```

During some trials, the mode can't change and the request returns `400`.

### Seat new joiners before their first pull request

In an Enterprise SSO workspace, Automatic mode assigns a seat only when someone opens a pull request. To give a new joiner a seat earlier, for example when your HR system adds them, call [Assign or unassign seats for multiple users](https://docs.coderabbit.ai/api/reference/manage-seats.md) with a workspace token and send their email with `"seat_assigned": true` in `members`. CodeRabbit creates the workspace member when the email is new. To link their Git account in the same request, add it in `identities`. [Manage seats and identities](https://docs.coderabbit.ai/management/sso/user-management-api.md#manage-seats-and-identities) shows the body.

## Change roles

1. Pick the role ID: `cr_admin` for Admin, `cr_member` for Member, or a custom role's UUID. On GitHub Cloud, [List organization roles](https://docs.coderabbit.ai/api/reference/list-roles.md) returns every role ID. It is a product operation, so a workspace token must [select the organization](https://docs.coderabbit.ai/api/authentication.md#select-an-organization). On other platforms, read the `role` field of a user who already has the custom role in the [user list](#list-users). The API can't assign Billing Admin (`cr_billing_admin`) or change the role of a Billing Admin.

2. Call [Change roles for multiple users](https://docs.coderabbit.ai/api/reference/change-roles.md) with `role` and up to 500 Git provider user IDs in `user_ids`. A workspace token also needs [`org_id`](https://docs.coderabbit.ai/api/authentication#select-an-organization), the `provider_organization_id` that [List organizations](https://docs.coderabbit.ai/api/reference/organizations-list.md) returns.

   ```bash theme={null}
   curl "https://api.coderabbit.ai/v1/users/roles" \
     --request POST \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"role": "cr_admin", "user_ids": ["121358802"]}'
   ```

   With a workspace token, add the organization in `org_id`:

   ```bash theme={null}
   curl "https://api.coderabbit.ai/v1/users/roles" \
     --request POST \
     --header "x-coderabbitai-api-key: $CODERABBIT_WORKSPACE_TOKEN" \
     --header "Content-Type: application/json" \
     --data '{"role": "cr_admin", "user_ids": ["121358802"], "org_id": "98765432"}'
   ```

3. Check `status`, `succeeded`, and `failed`, as for seats. A `CANNOT_CHANGE_BILLING_ADMIN_ROLE` failure marks a Billing Admin.

### Change a role on every organization of a self-hosted instance

With a self-hosted instance key, set `org_id` to `ALL`, in any case, to apply the change to every active organization on the instance, or to one organization's ID to change only that organization.

CodeRabbit writes each organization separately, so an `ALL` change isn't atomic. A user is listed in `succeeded` only when the change succeeded in every organization. If any organization failed, the user is listed in `failed` with the first error code; send the request again for those users. Other key types that send `ALL` get `400 INVALID_REQUEST`.

## Create and edit custom roles

The custom role operations are product operations, so they work for GitHub Cloud organizations; check [which keys they accept](https://docs.coderabbit.ai/api/authentication.md#which-keys-each-operation-accepts). Use a workspace token with one of the workspace's GitHub Cloud organizations [selected](https://docs.coderabbit.ai/api/authentication.md#select-an-organization), or a user key from one of them. A user key's owner needs the Role Management permission in that organization: `role_management:read` to list and read roles, `role_management:write` to create and update them, and `role_management:delete` to delete them. The built-in Admin role has all three. Billing Admin has only read and can't create API keys. A workspace admin who needs this key creates it in an organization where they hold the Admin role.

Every organization in a workspace shares the same custom roles. In a workspace with several organizations, such as an Enterprise SSO workspace, create a role once with a key from any of its GitHub Cloud organizations, and the role is available in all of them. You still assign it per organization.

1. Call [List supported role permissions](https://docs.coderabbit.ai/api/reference/list-role-permission-options.md) to get the `resource_ids` and `access_types` (`read`, `write`, `delete`) a role can hold.
2. Call [Create a custom role](https://docs.coderabbit.ai/api/reference/create-role.md) with `name`, an optional `description`, and an optional `duplicate_from`, the ID of the role to copy. This operation doesn't accept permissions. The response returns the new role with its ID in `role`.
3. Call [Update a custom role](https://docs.coderabbit.ai/api/reference/update-role.md) with the role's complete `name` and its full `permissions` list, each entry with a `resource_id` and an `access_type`. The list replaces all of the role's permissions.
4. Assign the role to users with [Change roles](#change-roles), once for each organization where they need it.

[List organization roles](https://docs.coderabbit.ai/api/reference/list-roles.md) returns role metadata without permissions or member counts; [Read a role and its permissions](https://docs.coderabbit.ai/api/reference/get-role.md) returns one role's permissions. [Delete an unassigned custom role](https://docs.coderabbit.ai/api/reference/delete-role.md) works only when no user has the role. For what each permission controls, see [Custom roles and permissions](https://docs.coderabbit.ai/management/custom-roles.md).

## Add users to a self-hosted organization

This operation works only for organizations on self-hosted CodeRabbit or on a self-managed Git provider.

1. Call [Add users and assign seats for a self-hosted organization](https://docs.coderabbit.ai/api/reference/add-users.md) with up to 500 entries in `users`, each with the Git provider `user_id` and `user_name`, and optionally `email` and `name`.
2. Check `status`, `succeeded`, and `failed` for each user.

If no seat is free, CodeRabbit can reclaim seats from users who have been inactive for at least 30 days. A repeated `user_id` is processed once, using its first entry. SSO workspaces can't use this operation and get `400 SSO_WORKSPACE_UNSUPPORTED`; use [workspace seat management](https://docs.coderabbit.ai/management/sso/user-management-api.md#manage-seats-and-identities) instead.

## Read audit logs

1. Call [List audit log entries](https://docs.coderabbit.ai/api/reference/audit-logs-list.md), filtered by actor, action, resource type, or date range. Write `date_from` and `date_to` as UTC timestamps that end in `Z`: a date without a time, or a time with an offset such as `+02:00`, returns `400`.

   ```bash theme={null}
   curl --get "https://api.coderabbit.ai/v1/audit-logs" \
     --header "x-coderabbitai-api-key: $CODERABBIT_API_KEY" \
     --data-urlencode "date_from=2026-10-01T00:00:00.000Z" \
     --data-urlencode "date_to=2026-10-31T23:59:59.999Z" \
     --data-urlencode "actions=create,delete" \
     --data-urlencode "page_size=100"
   ```

2. Read `data` for the entries and `filter_options` for the values you can filter by. Each entry's `createdAt` is a UTC timestamp.

3. While `pagination.has_next_page` is `true`, increase `page` by one and repeat the request. `page_size` accepts up to 100.

The response is JSON only. The operation has no CSV option, and unknown query parameters, including `format`, return `400`. To hand the log to a tool that expects CSV, collect every page and convert the entries.

With a workspace token, omit `org_id` to read every organization in the workspace together with workspace-level events. For what CodeRabbit logs, see [Audit Logs](https://docs.coderabbit.ai/management/audit-logs.md).

## Handle errors

| Response | What to do |
| - | - |
| `410 LEGACY_API_KEY` | Replace the key marked **Legacy** with a new API key; those keys can't use these operations. |
| `403 SSO_WORKSPACE_ORG_KEY_FORBIDDEN` | Use a workspace API token in an SSO workspace. |
| `403 NOT_ADMIN` | Use a key whose owner has the Admin role. |
| `403 FORBIDDEN` | Give the key owner's role the permission the operation needs. |
| `403 SELF_HOSTED_ONLY` | Change the seat assignment mode in the app, as described in [Set the seat assignment mode](#set-the-seat-assignment-mode). |
| `402 NO_ACTIVE_SUBSCRIPTION` | Renew the subscription. |
| `429` | Wait for the `Retry-After` interval, then retry. |

For response formats and other codes, see [Errors](https://docs.coderabbit.ai/api/conventions.md#errors) and [Rate limits](https://docs.coderabbit.ai/api/conventions.md#rate-limits).

## What's next

> [card] [SSO user management API](https://docs.coderabbit.ai/management/sso/user-management-api.md)
>
> Manage workspace members, seats, and linked Git identities with a workspace API token.

> [card] [Seat assignment](https://docs.coderabbit.ai/management/seat-assignment.md)
>
> Learn how automatic and manual seat assignment work and when seats are released.

> [card] [Custom roles and permissions](https://docs.coderabbit.ai/management/custom-roles.md)
>
> Decide which permissions each custom role grants before you script role changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.