---
title: "Seats"
method: POST
path: "/v1/users/seats"
---

# Seats

`POST /v1/users/seats`

Bulk assign or unassign seats for up to 500 users. The request format depends on the type of API key used. **Organization and self-hosted instance API keys** address users by provider user ID with the `action` + `user_ids` format, where the `action` field determines the operation type. **Workspace API keys** address users by email or CodeRabbit user ID (`cr_user_id`) with the `members` format, where each entry declares its desired seat state via `seat_assigned`. Sending the `action` + `user_ids` format with a workspace API key (or the `members` format with an organization key) fails with an `INVALID_REQUEST` error.

## Headers

- `x-coderabbitai-api-key` string, required

## Request body

- union
  - ManageSeatsRequest — Request to manage user seats with an organization or self-hosted instance API key. Users are addressed by provider user ID.
    - `action` 'assign' | 'unassign', required — Action to perform
    - `user_ids` string[], required — Array of provider user IDs
  - ManageSeatsMembersRequest — Request to manage user seats with a workspace API key. Members are addressed by email or CodeRabbit user ID, and each entry declares its desired seat state.
    - `members` union[], required — Array of members to update. Each member is identified by `email` or `cr_user_id` (at least one required; `cr_user_id` takes precedence when both are provided).
      - union — One member to update. Identify the member by `email` or `cr_user_id` — at least one is required, and `cr_user_id` takes precedence when both are provided.
        - object
          - `email` string, email, required — Email address of the member (unique per workspace). The only identifier that can enroll a member not yet known to CodeRabbit.
          - `cr_user_id` string, uuid — CodeRabbit user ID of an existing member — the `user_id` returned by `GET /v1/users` when using a workspace key. Use it to address members who have no email. Never enrolls a new member: an unknown ID fails that entry with `USER_NOT_FOUND`.
          - `seat_assigned` boolean — Desired seat state: `true` assigns a seat, `false` unassigns it. Omit to leave the member's seat unchanged.
          - `identities` object[] — Declarative replacement of the member's full Git provider identity set. Omit to leave identities untouched; an empty array removes all identities.
            - `provider` string, required — Git platform provider of this identity
            - `self_hosted_instance_url` string — Host URL of the self-hosted instance this identity belongs to. Omit for cloud identities. The URL must match a self-hosted instance registered to the workspace.
            - `user_id` string, required — Provider user ID
            - `username` string — Provider username
            - `name` string — Display name
        - object
          - `email` string, email — Email address of the member (unique per workspace). The only identifier that can enroll a member not yet known to CodeRabbit.
          - `cr_user_id` string, uuid, required — CodeRabbit user ID of an existing member — the `user_id` returned by `GET /v1/users` when using a workspace key. Use it to address members who have no email. Never enrolls a new member: an unknown ID fails that entry with `USER_NOT_FOUND`.
          - `seat_assigned` boolean — Desired seat state: `true` assigns a seat, `false` unassigns it. Omit to leave the member's seat unchanged.
          - `identities` object[] — Declarative replacement of the member's full Git provider identity set. Omit to leave identities untouched; an empty array removes all identities.
            - `provider` string, required — Git platform provider of this identity
            - `self_hosted_instance_url` string — Host URL of the self-hosted instance this identity belongs to. Omit for cloud identities. The URL must match a self-hosted instance registered to the workspace.
            - `user_id` string, required — Provider user ID
            - `username` string — Provider username
            - `name` string — Display name

## Response `200`

Operation completed (check status field for partial failures). The `succeeded` and `failed` entries echo the identifiers used in the request: provider user IDs for organization and self-hosted instance keys; for workspace keys, whichever identifier each member supplied (`cr_user_id` when provided, otherwise `email`).

- BulkOperationResponse — Response for bulk operations with partial success model
  - `status` 'success' | 'partial_success' | 'failure', required — Operation status: 'success' if all succeeded, 'partial_success' if some succeeded, 'failure' if all failed
  - `succeeded` string[], required — Array of user IDs that were successfully processed
  - `failed` BulkOperationFailure[], required — Array of failures with error details
    - `user_id` string, required — Identifier that failed: a provider user ID, or the supplied `cr_user_id`/`email` when the request used a workspace API key
    - `code` string, required — Error code

## Other responses

- `400` — Invalid request
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Not an admin or missing Enterprise plan
- `410` — Legacy API key - deprecated and no longer supported for user management
- `429` — Rate limit exceeded (10 requests per 60 seconds per organization)
- `500` — Internal server error

---

[API](https://skmtc.net/coderabbit/apis/coderabbit-api-spec.md) · [All operations](https://skmtc.net/coderabbit/apis/coderabbit-api-spec/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coderabbit/coderabbit-api-spec/versions/401789d85d01/schema)