Authenticate API requests

Every REST request, and every coderabbit api command, authenticates with an API key that you send in the x-coderabbitai-api-key header. A key belongs to a person: it acts with that person’s current role and access, and never with more. The hosted MCP server doesn’t use API keys; it signs you in with OAuth instead.

Key types

Key type	What it is	Create it in
User key	A key for reading and exporting data and for automation that doesn’t run reviews. It doesn’t need a seat.	API keys, type User
Agentic key	A key for agents and CI jobs that run CodeRabbit reviews, such as the CLI in headless mode. Its owner must hold a seat, and the key stops working when they lose it.	API keys, type Agentic
Workspace API token	A token for an Enterprise SSO workspace admin that works across every organization in the workspace.	Workspace management > API tokens. See Workspace API tokens.
Self-hosted instance key	A user or agentic key created in an organization on self-hosted CodeRabbit or on a self-managed Git provider, such as GitHub Enterprise Server or GitLab Self-Managed. It acts on that whole instance rather than one organization.	API keys in that organization

The API keys list shows each key’s type in the Type column. Keys marked Legacy aren’t tied to a person. Product operations reject them, and the user, audit log, Deep Scan findings, and Bug Scan findings operations return 410 LEGACY_API_KEY. Replace them with a user or agentic key.

Which key for which job

Job	Use	Why
A script that reads data, such as pull requests and their review status	User key	Reads don’t need a seat, and the built-in Member role can create user keys.
An unattended service that also requests reviews, such as a bot that runs coding tasks and then asks for a review	Agentic key	Requesting a review needs an agentic key, and the same key works for most other product operations. Its owner needs a seat.
A scheduled export of metrics, credits, audit logs, or Deep Scan and Bug Scan findings	User key, owned by an account that stays with the organization, such as one kept for automation	Metrics, audit logs, and the scan findings exports refuse agentic keys. The owner’s role must allow each export, and credit balances also need permission to read the subscription, which the Admin role has and the Member role doesn’t.
User and seat management across the organizations of an Enterprise SSO workspace	Workspace API token	One token covers every organization in the workspace, and in an SSO workspace only a workspace API token can list users and manage seats.
An AI agent, such as Claude or Codex	The hosted MCP server, with OAuth	The agent never holds a key, and you approve the scopes it asks for.

Organizations on self-hosted CodeRabbit or on a self-managed Git provider use a self-hosted instance key of type User for exports and user management.

Create a user or agentic key

Open API keys

In the CodeRabbit app, open API keys for the US region or the EU region. Organizations on a self-managed Git provider or on self-hosted CodeRabbit find the page at /settings/account/api-keys.

Create the key

Choose Create API key. Select the Type, enter a name that says what the key is for, and choose an Expiration: 7, 30, or 90 days, 1 year, a custom date up to a year away, or No expiration.

Copy the key

Choose Save API key and copy the key. CodeRabbit shows it only once. Keys start with cr-.

Type offers only the types you can create:

User needs a role that can manage API keys. The built-in Admin and Member roles can. For a custom role, see custom roles.
Agentic needs an assigned seat in the organization.

If Create API key is unavailable, ask an organization admin to check your role and seat. Billing administrators can’t create API keys.

Which keys each operation accepts

The API has two families of operations, and they accept different keys:

Product operations are the GitHub Cloud operations: identity, repositories, pull requests and reviews, Coding Agent, coding environments, Verify, Triage, security scans and findings, Knowledge Base, automations, reports, configuration, connections, custom roles, and usage. They accept user and agentic keys, workspace API tokens with a selected organization, and connections through the hosted MCP server, which offers most of them as tools.
Export and user-management operations are the operations under /v1/users, /v1/audit-logs, /v1/metrics, /v1/learnings, /v1/organizations, and /v1/linked-repositories, plus Deep Scan code findings at /v1/security/scans/code and Bug Scan findings at /v1/bug-scan/findings. They work on every Git platform CodeRabbit supports.

Operations	User key	Agentic key	Workspace API token	Self-hosted instance key (user type)
Product operations	Yes	Yes, except changes to configuration and connections, including custom roles: `403 forbidden`	Yes, with a selected organization	No: `404 not_found`
Users, seats, and role changes under `/v1/users`	Yes	Yes	Yes	Yes
Other export and user-management operations	Yes	No: `403 KEY_TYPE_FORBIDDEN`	Yes	Yes

A few operations add their own rule:

With a workspace API token, product operations act on one GitHub Cloud organization of the workspace, so every request needs an organization selector. For operations that act on repositories, the token’s owner also needs their GitHub account connected in the workspace; without it, the request fails with the message “Connect the API key owner’s GitHub account in this workspace.”
Requesting a pull request review needs an agentic key, because the review uses its owner’s seat.
In an Enterprise SSO workspace, listing users and managing seats need a workspace API token. User and agentic keys get 403 SSO_WORKSPACE_ORG_KEY_FORBIDDEN.
Adding users and changing the seat assignment mode work only for organizations on self-hosted CodeRabbit or a self-managed Git provider.
A self-hosted instance key of type Agentic is refused wherever the table refuses an agentic key.

See Availability for plans and Git platforms.

Send the key

Send the key in the x-coderabbitai-api-key header over HTTPS:

curl -sS https://api.coderabbit.ai/v1/me \
  -H "x-coderabbitai-api-key: $CODERABBIT_API_KEY"

Use the base URL for your organization’s region; see Base URLs and regions. CodeRabbit returns 401 when the header is missing, the key is unknown, deleted, or expired, or an agentic key’s owner no longer holds a seat. In the CLI, pass the key with --api-key-file, or sign in once with an agentic key. See CLI.

Select an organization

A user or agentic key belongs to the organization it was created in, and every request acts on that organization. A self-hosted instance key acts on its instance. A workspace API token isn’t bound to one organization. Select one with one of two selectors, never both:

org_name is the GitHub login of a GitHub Cloud organization in the workspace, such as coderabbitai. Matching ignores letter case. Use the organization’s current login: display names and earlier logins don’t match. Name selection is turned on per organization; where it isn’t on, or where a name matches more than one organization, use org_id.
org_id is the Git provider’s ID for an organization in the workspace, such as the numeric ID of a GitHub organization. It works on every Git platform.

Send the selector here:

Reads take it as a query parameter. Export and user-management reads cover the whole workspace when you omit it, and one organization when you pass it. Product operations always need it.
Changes that act on one organization need it: in the JSON body for POST, PUT, and PATCH, and in the query string for DELETE. Seat management works across the workspace by email address and takes no selector.

A missing selector where one is needed, or both selectors at once, returns 400. An organization that isn’t active in the workspace returns 404, and a token whose owner is no longer a workspace admin returns 403. CodeRabbit also refuses a key or token whose owner was archived from the subscription. Workspace API tokens lists what each export and user-management operation does with and without a selector. Don’t send org_name or org_id with other keys: product operations reject either one with 400 invalid_request. A self-hosted instance key can pass org_id to change roles in one organization on the instance, or "ALL" for every organization on it. org_id differs from the CodeRabbit organization ID that Get the authenticated principal returns in scope.id. See Identifiers.

Permissions

A key carries its owner’s permissions, checked again on every request:

User and agentic keys act with the owner’s current role in the organization, such as Admin, Member, or a custom role. An agentic key identifies its owner; it doesn’t grant extra permissions.
Workspace API tokens act as an admin of the selected organization, and only while the token’s owner is a workspace admin.
Plans and product settings still apply. A key can’t use a product that the organization’s plan or settings don’t include.

When the owner’s role changes, their keys change with it. A 403 forbidden usually means the owner’s role lacks the permission, the key type isn’t accepted, or the owner can’t access the repository.

Store and rotate keys

Store keys in a secrets manager or your CI system’s secret store, and expose them to jobs as environment variables. Never commit a key or put it in a URL.
For the CLI, keep the key in a file that only you can read and pass it with --api-key-file. The file must contain only the key.
Give each script or integration its own key and an expiration date, so you can revoke one without breaking the others.
To rotate a key, create the new key, switch your integration to it, then delete the old key from the API keys list. A deleted key stops working immediately.
Keys start with cr-, which helps secret scanners find leaked keys. Delete a leaked key right away.

People whose role can manage users can turn on Show member keys on the API keys page to review and delete keys that others created.

AI agents and the MCP server

The hosted MCP server authenticates with OAuth instead of a key. You sign in to CodeRabbit in the browser, choose an organization, and approve the scopes the agent asks for. The agent never receives a key, and you can grant read access without granting changes.

What’s next

Handle responses

Learn the base URLs, identifiers, pagination, errors, and rate limits shared by every operation.

Use workspace API tokens

Create one token that works across every organization of an Enterprise SSO workspace.

Connect an MCP client

Set up the hosted MCP server with OAuth in Claude, Codex, or another client.

Basics

Clients

Guides

API reference