> ## 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.

# Workspace API tokens

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

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 <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="building-2" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<EnterprisePlanBadge />

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

<Steps>
  <Step title="Open Workspace API Tokens">
    In the CodeRabbit app, open **Workspace Settings** > **API Tokens**.
  </Step>

  <Step title="Create the token">
    Choose **Create API token**, enter a name, and select an expiration date.
  </Step>

  <Step title="Copy the token">
    Copy the token value immediately. CodeRabbit shows the token only once.
  </Step>
</Steps>

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

```bash theme={null}
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`](/api-reference/organizations-list)                                            | Return every active organization in the workspace.                                                                                                                                               |
| [`GET /v1/organizations/{organization_id}/repositories`](/api-reference/organization-repositories-list) | Return the active repositories for an organization in the workspace. Use the CodeRabbit organization UUID returned by `GET /v1/organizations`.                                                   |
| [`GET /v1/users`](/api-reference/users-list)                                                            | Omit `org_id` for a workspace-wide people view, or pass `org_id` to return users for one organization.                                                                                           |
| [`POST /v1/users/seats`](/api-reference/users-manage-seats)                                             | Manage seats workspace-wide by email address. Do not pass `org_id`.                                                                                                                              |
| [`POST /v1/users/roles`](/api-reference/users-change-roles)                                             | Pass `org_id` in the request body to select the target organization.                                                                                                                             |
| [`/v1/roles`](/api-reference/roles-list)                                                                | 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`](/api-reference/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`](/api-reference/metrics-data-api)                                            | Omit `org_id` for workspace-wide review metrics, or pass `org_id` to scope the result to one organization.                                                                                       |
| [`GET /v1/metrics/mcp`](/api-reference/mcp-metrics)                                                     | Omit `org_id` for workspace-wide MCP usage metrics, or pass `org_id` to scope the result to one organization.                                                                                    |
| [Learnings API](/api-reference/learnings-list)                                                          | For `GET`, omit `org_id` for Learnings across the workspace or pass it to scope the result to one organization. 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:

<Info>
  The organization inventory APIs do not use `org_id`. Pass the CodeRabbit organization UUID returned in the `id` field from [`GET /v1/organizations`](/api-reference/organizations-list) as the `organization_id` path parameter when listing repositories.
</Info>

* **Endpoints that require `org_id`** (`POST /v1/users/roles`, the `/v1/roles` operations, and Learnings 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](/api-reference/users-change-roles) for details.

## What's next

<CardGroup cols={1}>
  <Card title="Review the API reference" href="/api-reference/users-list" icon="braces" horizontal>
    Explore request parameters and response schemas for the supported public APIs
  </Card>

  <Card title="Manage custom roles" href="/management/custom-roles" icon="shield-check" horizontal>
    Define role permissions for organizations in your Enterprise SSO workspace
  </Card>

  <Card title="Review audit logs" href="/management/audit-logs" icon="scroll-text" horizontal>
    Track administrative activity across the workspace
  </Card>
</CardGroup>