> ## 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.
# SSO user management API
> Use workspace API tokens to list SSO workspace members, manage seats, and repair linked provider identities.
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}
;
};
export const AdminRoleBadge = ({tip = "This feature requires an organization owner, an admin role or the corresponding permission. Regular Members do not have access.", title = "Admin Only", cta = "View roles", href = "/management/roles", disabled = false}) => {
return
{title}
;
};
Use this guide when your Enterprise SSO workspace needs to manage people across multiple connected Git providers through the CodeRabbit API. SSO workspace user management is person-centric after provider accounts are linked: CodeRabbit counts and assigns seats on the workspace member, then mirrors that state to the linked provider accounts used for pull request reviews.
For the generated endpoint reference, see [`GET /v1/users`](/api-reference/users-list) and [`POST /v1/users/seats`](/api-reference/users-manage-seats). Because the request body depends on the API key type, use the examples on this page for SSO workspace tokens and the generated reference for shared endpoint details.
## How SSO workspace users work
An SSO workspace can connect multiple Git providers. The same person might have a GitHub account, a GitLab account, and a self-hosted GitLab account.
CodeRabbit cannot always know which provider accounts belong to the same person. Until those accounts are linked to one workspace user, each account can be treated as a separate identity and can consume its own seat.
Link the provider accounts to one workspace user to count that person as one seat across providers. You can link accounts in **Workspace Team Management**, or use this API for automation and bulk updates.
After accounts are linked, CodeRabbit stores the seat assignment on the workspace user and applies it to all linked provider accounts used for pull request reviews.
## Before you start
Make sure you have:
* Enterprise SSO enabled for the workspace
* A [workspace API token](/api/workspace-api-tokens)
* Workspace admin access for the token owner
* The email address for each person in the update, or their CodeRabbit user ID (the `cr_user_id` from `GET /v1/users`) for members who do not have an email
* Provider user IDs for the Git identities you plan to link or repair. See [Find provider user IDs](#find-provider-user-ids).
Pass the token in the `x-coderabbitai-api-key` header:
```bash theme={null}
curl --request GET \
--url 'https://api.coderabbit.ai/v1/users?limit=100' \
--header 'x-coderabbitai-api-key: '
```
## List workspace users
Use `GET /v1/users` with a workspace API token and omit `org_id` to list the whole SSO workspace as one roster.
```bash theme={null}
curl --request GET \
--url 'https://api.coderabbit.ai/v1/users?seat_filter=all&limit=100' \
--header 'x-coderabbitai-api-key: '
```
The response returns one row per CodeRabbit user. The `accounts` array lists the provider identities linked to that person.
```json theme={null}
{
"seats_purchased": 50,
"seats_assigned": 12,
"seat_assignment_mode": "manual",
"users": [
{
"cr_user_id": "cru_123",
"seat_assigned": true,
"role": null,
"email": "jane@acme.com",
"workspace_role": "cr_admin",
"accounts": [
{
"provider": "github",
"self_hosted": false,
"organization_id": "123456",
"user_id": "121358802",
"username": "jane",
"role": "cr_admin"
},
{
"provider": "gitlab-self-hosted",
"self_hosted": true,
"instance_url": "https://gitlab.acme.com",
"user_id": "77",
"username": "jane.g",
"role": null
}
]
}
],
"next_cursor": null
}
```
Use `seat_filter=assigned` or `seat_filter=unassigned` to filter by the workspace seat state. To filter by provider-account linking status, use `linked=true` for members who have an email address and at least one active linked account, or `linked=false` for members who have no email address or no active linked accounts. CodeRabbit applies the linked-status filter before cursor pagination. Use `cursor` with the `next_cursor` value from the previous response to fetch the next page.
The `linked` filter is available only for the workspace-wide SSO roster. If you include `org_id` with a workspace token, CodeRabbit resolves that provider organization inside the workspace and returns the regular organization-scoped user list instead; including `linked` in that request returns `400 INVALID_REQUEST`. Non-SSO requests that include `linked` also return `400 INVALID_REQUEST`.
## Manage seats and identities
Use `POST /v1/users/seats` with a workspace API token to create or update SSO workspace members. Identify each member by `email` or by `cr_user_id` (the `cr_user_id` returned by `GET /v1/users`). The request body uses a `members` array.
```bash theme={null}
curl --request POST \
--url 'https://api.coderabbit.ai/v1/users/seats' \
--header 'content-type: application/json' \
--header 'x-coderabbitai-api-key: ' \
--data '{
"members": [
{
"email": "jane@acme.com",
"seat_assigned": true
}
]
}'
```
Each member can include these fields:
| Field | Required | Description |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | Conditional | The workspace member email address, used as the member key inside the SSO workspace. Required unless you provide `cr_user_id`. When present, CodeRabbit resolves the member by email and creates the member if it does not exist yet. |
| `cr_user_id` | Conditional | The CodeRabbit user ID of an existing workspace member — the `cr_user_id` returned by `GET /v1/users` (distinct from the provider `identities[].user_id`). Provide it instead of `email` to manage members that have no email, such as unlinked users. Required unless you provide `email`. If you send both, CodeRabbit uses `cr_user_id` and ignores `email`. CodeRabbit never creates a member from `cr_user_id`; an unknown ID fails that member with `USER_NOT_FOUND`. |
| `seat_assigned` | No | Set to `true` to assign a seat or `false` to remove a seat. Omit the field to leave the current seat state unchanged. |
| `identities` | No | Replace the member's full linked provider identity set with exactly the identities you send. Omit the field to leave identities unchanged. Use an empty array to remove all linked identities. |
Each identity can include these fields:
| Field | Required | Description |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `provider` | Yes | The lowercase API value for the Git provider. Use the values in [Find provider user IDs](#find-provider-user-ids). |
| `user_id` | Yes | The provider user ID for that identity. |
| `self_hosted_instance_url` | No | The self-hosted instance URL for self-hosted identities. The URL must match a host registered in the workspace. |
| `username` | No | The provider username to display in CodeRabbit. |
| `name` | No | The provider display name to display in CodeRabbit. |
### Find provider user IDs
Use `identities[].user_id` for the stable user identifier CodeRabbit receives from the Git provider. The value is usually not the display name, and it can differ from the username shown in the provider UI.
If the account is already linked in CodeRabbit, first call `GET /v1/users` and reuse the value from `accounts[].user_id`. If you are repairing an account that is not linked yet, collect the ID from the provider.
| Provider | `provider` value | Use this `user_id` |
| ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub | `github` | Use the numeric GitHub user ID. Call the GitHub REST API for the user and copy the `id` field. |
| GitHub Enterprise Server | `github-self-hosted` | Use the numeric user ID from that GitHub Enterprise Server instance and include `self_hosted_instance_url`. |
| GitLab | `gitlab` | Use the numeric GitLab user ID. Open the user's profile or admin user page, or call the GitLab Users API and copy the `id` field. |
| Self-hosted GitLab | `gitlab-self-hosted` | Use the numeric GitLab user ID from that self-hosted GitLab instance and include `self_hosted_instance_url`. |
| Bitbucket Cloud | `bitbucket` | Use the Bitbucket user `uuid` from the workspace member or `/2.0/user` response. Do not use `account_id` or display name as the provider `user_id`. |
| Bitbucket Data Center | `bitbucket-self-hosted` | Use the numeric user ID from the Bitbucket Data Center user record. Include `self_hosted_instance_url` for the Data Center instance. |
| Azure DevOps | `azure-devops` | Use the user principal name returned by Azure DevOps, normalized to lowercase by CodeRabbit. In most workspaces this is the user's email address. If the provider record does not have a principal name, CodeRabbit falls back to the mail address. |
### Assign a seat
```json theme={null}
{
"members": [
{
"email": "jane@acme.com",
"seat_assigned": true
}
]
}
```
### Remove a seat
```json theme={null}
{
"members": [
{
"email": "jane@acme.com",
"seat_assigned": false
}
]
}
```
### Manage a member without an email
Some workspace members have no email address, such as unlinked users whose provider accounts are not yet tied to a person. Because those members have no email key, identify them by `cr_user_id` instead. Read the `cr_user_id` from `GET /v1/users` and send it as `cr_user_id`.
Remove a seat from a member by CodeRabbit user ID:
```json theme={null}
{
"members": [
{
"cr_user_id": "cru_123",
"seat_assigned": false
}
]
}
```
`cr_user_id` works for any member, including members that also have an email, and you can combine it with `seat_assigned` and `identities` in the same request. CodeRabbit never creates a member from `cr_user_id`; if the ID does not match a member in the workspace, that member fails with `USER_NOT_FOUND`. If a payload includes both `email` and `cr_user_id`, CodeRabbit uses `cr_user_id`.
### Repair linked identities
Include `identities` when you need CodeRabbit to link, move, or repair the provider accounts for a person. When `identities` is present, CodeRabbit treats it as the full identity set for that member.
```json theme={null}
{
"members": [
{
"email": "jane@acme.com",
"seat_assigned": true,
"identities": [
{
"provider": "github",
"user_id": "121358802",
"username": "jane"
},
{
"provider": "gitlab-self-hosted",
"self_hosted_instance_url": "https://gitlab.acme.com",
"user_id": "77",
"username": "jane.g",
"name": "Jane Doe"
}
]
}
]
}
```
### Remove all linked identities
Send an empty `identities` array to remove all provider links for a member while keeping the workspace member record.
```json theme={null}
{
"members": [
{
"email": "jane@acme.com",
"identities": []
}
]
}
```
## Response format
The response uses the same bulk operation shape as the standard seat management API. For workspace-token requests, the `succeeded` array and each `failed.user_id` value echo the identifier you supplied for that member: the email address, or the `cr_user_id` when you identified the member that way.
```json theme={null}
{
"status": "partial_success",
"succeeded": [
"jane@acme.com"
],
"failed": [
{
"user_id": "bob@acme.com",
"code": "SEAT_NOT_AVAILABLE"
}
]
}
```
Common per-member failure codes include:
| Code | Meaning |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SEAT_NOT_AVAILABLE` | The requested seat assignment would exceed the workspace seat limit. |
| `NO_ACTIVE_SUBSCRIPTION` | The workspace does not have an active Enterprise subscription. |
| `USER_NOT_FOUND` | The `cr_user_id` does not match a member in this workspace. |
| `INVALID_REQUEST` | The member payload is invalid, such as a member with neither `email` nor `cr_user_id`, an unknown `self_hosted_instance_url`, or conflicting identities for the same provider slot. |
| `INTERNAL_ERROR` | CodeRabbit could not complete the member update because of an unexpected server error. |
## Compatibility
This workspace-token flow only applies to Enterprise SSO workspace management. Organization API keys and self-hosted organization keys continue to use the existing provider-user contract for `POST /v1/users/seats`:
```json theme={null}
{
"action": "assign",
"user_ids": [
"121358802",
"22605247"
]
}
```
Do not send the provider-user contract with a workspace API token. Do not send the `members` contract with an organization API key.
## What's next
Review the shared Enterprise SSO rollout flow and workspace administration model.
Learn how manual and automatic seat assignment work across CodeRabbit organizations and SSO workspaces.
Create a workspace-scoped token and review the supported APIs for Enterprise SSO workspaces.