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

# Authenticate to the Platform API

> Select the correct API key, organization, and MCP consent scopes for the Platform API.

The shared Platform API supports current user or agentic organization keys and workspace API tokens for GitHub Cloud organizations. Legacy organization keys are not supported by shared operations. Each request uses the key owner's current permissions; a key does not add repository access or product eligibility. Self-hosted instances are excluded from the shared API; legacy REST endpoints retain their own key requirements.

## Choose the organization

| Credential | Organization selection |
| - | - |
| Organization key | The key selects its organization. Omit `org_id`. |
| Workspace token | For shared operations, supply `org_id`, the Git provider's organization ID. The organization must belong to the workspace and the token owner must still be a workspace admin. For other REST endpoints, see [workspace token behavior](https://docs.coderabbit.ai/api/workspace-api-tokens.md#supported-apis). |
| Hosted MCP | The approved connection selects its organization. Tool inputs cannot override it. |

`org_id` is a **Git-provider ID**, which may be numeric text. `GET /me` returns a **CodeRabbit organization ID** in `scope.id`. Do not interchange them. For workspace credentials, place `org_id` in the location shown by the operation's schema: the query for reads or the JSON input for writes.

## Make a REST request

Send `x-coderabbitai-api-key` to your region's REST base URL: `https://api.coderabbit.ai/v1` in the US or `https://api.eu.coderabbit.ai/v1` in the EU. This US example supplies the header through standard input so the secret is not part of curl's command-line arguments.

```bash theme={null}
printf 'x-coderabbitai-api-key: %s\n' "$CODERABBIT_API_KEY" | \
  curl --fail-with-body --header @- \
  'https://api.coderabbit.ai/v1/me'
```

For a workspace token:

```bash theme={null}
printf 'x-coderabbitai-api-key: %s\n' "$CODERABBIT_WORKSPACE_API_KEY" | \
  curl --fail-with-body --header @- \
  'https://api.coderabbit.ai/v1/me?org_id=12345678'
```

The response identifies the key owner and selected organization. Successful authentication does not authorize every operation. Most product operations also require the owner's linked GitHub account and current membership; reconnect the account in CodeRabbit if requested.

Requesting a pull-request review through REST or CLI requires an agentic API key. A user API key returns `403 forbidden` for that action, even when it can read the pull request. Hosted MCP uses the separate review-request consent scopes described below.

## Use the same key with API mode

Use CodeRabbit CLI **0.9.4 or later** for API mode. The explicit key file takes precedence over a saved CLI login without changing that login. The file must contain only the key. An unreadable or empty file fails without falling back to another credential.

```bash theme={null}
coderabbit api --api-key-file /path/to/api-key me

coderabbit api --api-key-file /path/to/workspace-key me --org-id 12345678
```

For generic requests, include query parameters in the endpoint itself:

```bash theme={null}
coderabbit api --api-key-file /path/to/workspace-key \
  request '/code/tasks?org_id=12345678&page_size=20'
```

A compatible saved API-key login can also supply API mode. Browser-login credentials and dedicated product commands have their own authentication requirements; API mode does not convert them or relax those checks.

## Approve MCP access

Hosted MCP is available only for US organizations. Connect through CodeRabbit's hosted MCP flow, select your organization, and review the requested permissions. The consent page distinguishes reads from actions that change configuration, create work, or deliver code. Execution actions may consume credits or paid usage under your plan.

Every new shared tool requires `account:read` plus its operation scopes. Examples include `code:read`, `code:write`, `security:read`, `security:write`, and `configuration:write`. Read permission does not imply write permission. An existing grant does not automatically gain additional scopes.

Requesting a pull-request review with `request_pull_request_review` requires `account:read`, `pull_requests:read`, and `reviews:write`. Reading review status needs only the first two. The legacy `review` scope remains for local code review and does not authorize a pull-request review request; approve `reviews:write` through the hosted MCP consent flow when needed.

MCP uses the signed-in person's current identity and organization membership. It does not receive an API key or a provider credential. The same product authorization still applies after consent.

## Recover from an access error

| Result | Next step |
| - | - |
| `400 invalid_request` | Check identifiers and input fields, including `org_id` placement. |
| `401 unauthenticated` | Replace an expired or revoked key, or reconnect MCP. |
| `403 forbidden` | Check the owner's role, repository access, linked account, and MCP scopes. Agentic keys cannot perform configuration or connection writes. |
| `404 not_found` | Check endpoint availability and access to the requested resource. |
| `409 conflict` or `head_changed` | Reload the current resource before deciding whether to retry. |
| `413 payload_too_large` | Reduce the JSON request body before retrying. |
| `429 rate_limit_exceeded` (REST), or MCP `rate_limit_exceeded` | Wait for the provided retry duration. |
| `503 unavailable` | Retry after the required service recovers. |

See [Platform API boundaries](https://docs.coderabbit.ai/api/platform-api.md#boundaries) for operations that still require browser interaction or retain legacy key restrictions.

## What's next

> [card] [Try an API workflow](https://docs.coderabbit.ai/api/platform-workflows.md)
>
> Read a pull request or create a coding task with your selected credential.

> [card] [Read your API identity](https://docs.coderabbit.ai/api-reference/identity-get)
>
> Inspect the authenticated principal and selected organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.