> ## 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/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/learnings`](/api-reference/learnings-list)         | Omit `org_id` for learnings across the workspace, or pass `org_id` to scope the result to one organization.                 |

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

* **Endpoints that require `org_id`** (`POST /v1/users/roles` and the `/v1/roles` 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, and learnings) operate workspace-wide across every organization. Pass `org_id` on the 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>