Workspace API tokens

Create and use workspace-scoped API tokens for Enterprise SSO workspaces.

Workspace API tokens let Enterprise SSO workspace admins use one token across every organization in the workspace for supported public APIs.

Availability

Workspace API tokens are available only in Enterprise SSO workspaces. Open Workspace Settings > API Tokens or go to /workspace/api-keys in the CodeRabbit app.

Only workspace admins can create, list, or delete workspace API tokens. Non-admin workspace members cannot manage tokens, and CodeRabbit re-checks workspace admin access every time a workspace token is used.

Create a token

1. Open Workspace API Tokens

   In the CodeRabbit app, open Workspace Settings > API Tokens.

2. Create the token

   Choose Create API token, enter a name, and select an expiration date.

3. Copy the token

   Copy the token value immediately. CodeRabbit shows the token only once.

Use the token with the x-coderabbitai-api-key header:

curl "https://api.coderabbit.ai/v1/users" \
  -H "x-coderabbitai-api-key: $CODERABBIT_WORKSPACE_API_KEY"

Supported APIs

Workspace API tokens are supported on these public APIs:

API	Workspace token behavior
GET /v1/organizations	Return every active organization in the workspace.
GET /v1/organizations/{organization_id}/repositories	Return the active repositories for an organization in the workspace. Use the CodeRabbit organization UUID returned by GET /v1/organizations.
GET /v1/users	Omit org_id for a workspace-wide people view, or pass org_id to return users for one organization.
POST /v1/users/seats	Manage seats workspace-wide by email address. Do not pass org_id.
POST /v1/users/roles	Pass org_id in the request body to select the target organization.
/v1/roles	Pass org_id in the query string for GET and DELETE requests, and in the request body for POST and PATCH requests.
GET /v1/audit-logs	Omit org_id for workspace-wide audit logs, or pass org_id to scope the result to one organization.
GET /v1/metrics/reviews	Omit org_id for workspace-wide review metrics, or pass org_id to scope the result to one organization.
GET /v1/metrics/mcp	Omit org_id for workspace-wide MCP usage metrics, or pass org_id to scope the result to one organization.
Learnings API	For GET, omit org_id for Learnings across the workspace or pass it to scope the result to one organization. Create, update, and delete requests require org_id and the learning:write permission.

The organization inventory endpoints use organization_id, a CodeRabbit UUID returned by GET /v1/organizations. This differs from the Git provider org_id used by the endpoints below.

Organization scoping with org_id

org_id is the Git provider organization ID for an organization inside the token’s workspace. It controls which organization a workspace token targets:

The organization inventory APIs do not use org_id. Pass the CodeRabbit organization UUID returned in the id field from GET /v1/organizations as the organization_id path parameter when listing repositories.

• Endpoints that require org_id (POST /v1/users/roles, the /v1/roles operations, and Learnings create, update, and delete operations) act on the single organization you name. CodeRabbit returns 400 when a required org_id is omitted, 404 when the ID does not match an active organization in the workspace, and 403 when the token owner is no longer a workspace admin.
• Endpoints that omit org_id (users, seats, audit logs, review metrics, MCP usage metrics, and GET /v1/learnings) operate workspace-wide across every organization. Pass org_id on these read endpoints to scope the result to one organization instead.

Other key types treat org_id differently:

• Organization-scoped API keys remain bound to their authenticated organization and ignore org_id.
• Self-hosted instance API keys ignore org_id on the workspace-token read and custom-role endpoints above. The one exception is POST /v1/users/roles, which accepts a self-hosted-only "ALL" sentinel—see Assign roles for details.

What’s next

Review the API reference

Explore request parameters and response schemas for the supported public APIs

Manage custom roles

Define role permissions for organizations in your Enterprise SSO workspace

Review audit logs

Track administrative activity across the workspace