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
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
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
1
2
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.
3
Copy the key
Choose Save API key and copy the key. CodeRabbit shows it only once. Keys start with
cr-.- 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.
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/codeand Bug Scan findings at/v1/bug-scan/findings. They work on every Git platform CodeRabbit supports.
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.
Send the key
Send the key in thex-coderabbitai-api-key header over HTTPS:
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_nameis the GitHub login of a GitHub Cloud organization in the workspace, such ascoderabbitai. 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, useorg_id.org_idis 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.
- 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, andPATCH, and in the query string forDELETE. Seat management works across the workspace by email address and takes no selector.
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.
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.
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.