SSO user management API

Use workspace API tokens to list SSO workspace members, manage seats, and repair linked provider identities.

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 and POST /v1/users/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
• 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.

Pass the token in the x-coderabbitai-api-key header:

  curl --request GET \
    --url 'https://api.coderabbit.ai/v1/users?limit=100' \
    --header 'x-coderabbitai-api-key: <workspace-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.

  curl --request GET \
    --url 'https://api.coderabbit.ai/v1/users?seat_filter=all&limit=100' \
    --header 'x-coderabbitai-api-key: <workspace-api-key>'

The response returns one row per CodeRabbit user. The accounts array lists the provider identities linked to that person.

  {
    "seats_purchased": 50,
    "seats_assigned": 12,
    "seat_assignment_mode": "manual",
    "users": [
      {
        "cr_user_id": "cru_123",
        "seat_assigned": true,
        "role": null,
        "email": "[e-mail]",
        "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.

  curl --request POST \
    --url 'https://api.coderabbit.ai/v1/users/seats' \
    --header 'content-type: application/json' \
    --header 'x-coderabbitai-api-key: <workspace-api-key>' \
    --data '{
      "members": [
        {
          "email": "[e-mail]",
          "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.
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

  {
    "members": [
      {
        "email": "[e-mail]",
        "seat_assigned": true
      }
    ]
  }

Remove a seat

  {
    "members": [
      {
        "email": "[e-mail]",
        "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:

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

  {
    "members": [
      {
        "email": "[e-mail]",
        "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.

  {
    "members": [
      {
        "email": "[e-mail]",
        "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.

  {
    "status": "partial_success",
    "succeeded": [
      "[e-mail]"
    ],
    "failed": [
      {
        "user_id": "[e-mail]",
        "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:

  {
    "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

Enterprise SSO overview

Review the shared Enterprise SSO rollout flow and workspace administration model.

Seat assignment

Learn how manual and automatic seat assignment work across CodeRabbit organizations and SSO workspaces.

Workspace API tokens

Create a workspace-scoped token and review the supported APIs for Enterprise SSO workspaces.