Authenticate to 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.
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.

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:

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.

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:

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 for operations that still require browser interaction or retain legacy key restrictions.

Repository Configuration

Subscription & billing

Connections

Dashboard

Reports

Organization administration

Enterprise SSO

Self-hosted CodeRabbit

CodeRabbit API

Authenticate to the Platform API

Choose the organization

Make a REST request

Use the same key with API mode

Approve MCP access

Recover from an access error

What’s next

Try an API workflow

Read your API identity

​Choose the organization

​Make a REST request

​Use the same key with API mode

​Approve MCP access

​Recover from an access error

​What’s next

Try an API workflow

Read your API identity

Choose the organization

Make a REST request

Use the same key with API mode

Approve MCP access

Recover from an access error

What’s next