Skip to main content
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. See Authentication for the keys each operation accepts, including workspace API tokens for Enterprise SSO workspaces, and Conventions 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.
  • The curl examples read the key from CODERABBIT_API_KEY. The CLI examples use the coderabbit api command 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

In an SSO workspace, a workspace token covers every task that the API offers. For the general rules, see Which key for which job.

List users

  1. Call List all users in the organization. To find who has a seat or a role, filter by seat status or by role.
  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.
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

In an Enterprise SSO workspace, use a workspace API token and the members body described in Workspace tokens. 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.
  2. Call Assign or unassign seats for multiple users with the action to take and the users’ IDs in user_ids.
    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.

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

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 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.
  1. Read the current mode from seat_assignment_mode in the user list.
  2. Call Update the seat assignment mode with mode set to automatic or 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 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 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 returns every role ID. It is a product operation, so a workspace token must select the organization. On other platforms, read the role field of a user who already has the custom role in the user list. 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 with role and up to 500 Git provider user IDs in user_ids. A workspace token also needs org_id, the provider_organization_id that List organizations returns.
    With a workspace token, add the organization in org_id:
  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. Use a workspace token with one of the workspace’s GitHub Cloud organizations selected, 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 to get the resource_ids and access_types (read, write, delete) a role can hold.
  2. Call Create a custom role 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 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, once for each organization where they need it.
List organization roles returns role metadata without permissions or member counts; Read a role and its permissions returns one role’s permissions. Delete an unassigned custom role works only when no user has the role. For what each permission controls, see Custom roles and permissions.

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

Read audit logs

  1. Call List audit log entries, 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.
  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.

Handle errors

For response formats and other codes, see Errors and Rate limits.

What’s next

SSO user management API

Manage workspace members, seats, and linked Git identities with a workspace API token.

Seat assignment

Learn how automatic and manual seat assignment work and when seats are released.

Custom roles and permissions

Decide which permissions each custom role grants before you script role changes.