> ## 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.
# 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.
export const EnterprisePlanBadge = ({tip = "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.", title = "Enterprise Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
return
{title}
;
};
## Manage Seats
Requires **Admin** role. See [Role-based access](/management/roles) for details.
### Request format by API key type
The request body schema depends on the type of API key you authenticate with:
| API key type | Request format | Users addressed by |
| -------------------- | --------------------- | --------------------- |
| Organization | `action` + `user_ids` | Provider user ID |
| Self-hosted instance | `action` + `user_ids` | Provider user ID |
| Workspace | `members` | Email or `cr_user_id` |
Workspace API keys do not accept the `action` + `user_ids` format — sending it fails with `INVALID_REQUEST: Invalid input: expected array, received undefined`. Use the `members` format instead, where each entry declares its desired seat state with `seat_assigned`.
```bash theme={null}
curl --request POST \
--url 'https://api.coderabbit.ai/v1/users/seats' \
--header 'x-coderabbitai-api-key: ' \
--header 'content-type: application/json' \
--data '{"members":[{"email":"user@example.com","seat_assigned":true}]}'
```
Each member entry is identified by `email` or `cr_user_id` (the `user_id` returned by [`GET /v1/users`](/api-reference/users-list)) — at least one is required, and `cr_user_id` takes precedence when both are provided. Use `cr_user_id` to address members who have no email; unknown IDs fail that entry with `USER_NOT_FOUND` in the response's `failed` array.
## OpenAPI
````yaml post /v1/users/seats
openapi: 3.0.3
info:
title: CodeRabbit API spec
version: 1.0.0
servers:
- url: https://api.coderabbit.ai
security:
- ApiKeyAuth: []
paths:
/v1/users/seats:
post:
summary: Seats
description: >-
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.
operationId: manage-seats
parameters:
- name: x-coderabbitai-api-key
description: Your CodeRabbit API key
required: true
example: cr-xxxxxxxxxx
schema:
type: string
in: header
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ManageSeatsRequest'
- $ref: '#/components/schemas/ManageSeatsMembersRequest'
examples:
assign:
summary: Assign seats (organization or self-hosted instance key)
value:
action: assign
user_ids:
- '121358802'
- '22605247'
unassign:
summary: Unassign seats (organization or self-hosted instance key)
value:
action: unassign
user_ids:
- '121358802'
- '22605247'
assignByEmail:
summary: Assign seats (workspace key)
value:
members:
- email: jane@example.com
seat_assigned: true
- cr_user_id: 3f8e2a9c-6b1d-4e5a-9c7f-2d4b8a6e1c3b
seat_assigned: true
unassignByEmail:
summary: Unassign seats (workspace key)
value:
members:
- email: jane@example.com
seat_assigned: false
responses:
'200':
description: >-
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`).
content:
application/json:
schema:
$ref: '#/components/schemas/BulkOperationResponse'
example:
status: success
succeeded:
- '121358802'
- '22605247'
failed: []
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: BATCH_SIZE_EXCEEDED
message: Maximum 500 users per request
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: UNAUTHORIZED
message: Invalid or inactive API key
'403':
description: Forbidden - Not an admin or missing Enterprise plan
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: NOT_ADMIN
message: Only administrators can perform seat management operations
'410':
description: >-
Legacy API key - deprecated and no longer supported for user
management
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: LEGACY_API_KEY
message: >-
You are using a legacy API key. We are deprecating use of
legacy keys. Regenerate a new API key and retry the request.
'429':
description: Rate limit exceeded (10 requests per 60 seconds per organization)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: RATE_LIMIT_EXCEEDED
message: Rate limit exceeded. Max 10 requests per 60 seconds
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
X-RateLimit-Limit:
description: Maximum requests allowed per time window
schema:
type: integer
X-RateLimit-Remaining:
description: Always 0 when rate limited
schema:
type: integer
X-RateLimit-Reset:
description: Unix timestamp when the rate limit resets
schema:
type: integer
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
error:
code: INTERNAL_ERROR
message: Internal server error while listing users
security:
- ApiKeyAuth: []
components:
schemas:
ManageSeatsRequest:
type: object
title: Organization / self-hosted instance key
description: >-
Request to manage user seats with an organization or self-hosted
instance API key. Users are addressed by provider user ID.
properties:
action:
type: string
enum:
- assign
- unassign
description: Action to perform
user_ids:
type: array
items:
type: string
description: Array of provider user IDs
minItems: 1
maxItems: 500
required:
- action
- user_ids
additionalProperties: false
ManageSeatsMembersRequest:
type: object
title: Workspace key
description: >-
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.
properties:
members:
type: array
description: >-
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).
minItems: 1
maxItems: 500
items:
type: object
description: >-
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.
properties:
email:
type: string
format: email
description: >-
Email address of the member (unique per workspace). The only
identifier that can enroll a member not yet known to
CodeRabbit.
cr_user_id:
type: string
format: uuid
description: >-
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:
type: boolean
description: >-
Desired seat state: `true` assigns a seat, `false` unassigns
it. Omit to leave the member's seat unchanged.
identities:
type: array
description: >-
Declarative replacement of the member's full Git provider
identity set. Omit to leave identities untouched; an empty
array removes all identities.
items:
type: object
properties:
provider:
type: string
description: Git platform provider of this identity
self_hosted_instance_url:
type: string
description: >-
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:
type: string
description: Provider user ID
username:
type: string
description: Provider username
name:
type: string
description: Display name
required:
- provider
- user_id
additionalProperties: false
anyOf:
- title: Identified by email
required:
- email
- title: Identified by cr_user_id
required:
- cr_user_id
additionalProperties: false
required:
- members
additionalProperties: false
BulkOperationResponse:
type: object
description: Response for bulk operations with partial success model
properties:
status:
type: string
enum:
- success
- partial_success
- failure
description: >-
Operation status: 'success' if all succeeded, 'partial_success' if
some succeeded, 'failure' if all failed
succeeded:
type: array
items:
type: string
description: Array of user IDs that were successfully processed
failed:
type: array
items:
$ref: '#/components/schemas/BulkOperationFailure'
description: Array of failures with error details
required:
- status
- succeeded
- failed
additionalProperties: false
ApiError:
type: object
description: Standard API error response
properties:
error:
type: object
properties:
code:
type: string
description: Error code identifier
message:
type: string
description: Human-readable error message
required:
- code
- message
additionalProperties: false
required:
- error
additionalProperties: false
BulkOperationFailure:
type: object
description: Failed operation details
properties:
user_id:
type: string
description: >-
Identifier that failed: a provider user ID, or the supplied
`cr_user_id`/`email` when the request used a workspace API key
code:
type: string
description: Error code
required:
- user_id
- code
additionalProperties: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-coderabbitai-api-key
description: >-
API key for authentication. You can create an API key from the
CodeRabbit dashboard.
````