> ## 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 API requests > Choose a CodeRabbit API key type, create the key, send it with each request, and understand which permissions it carries. 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](https://docs.coderabbit.ai/api/mcp.md) 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](https://docs.coderabbit.ai/cli/headless-cli-integration.md). 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](https://docs.coderabbit.ai/management/sso.md) workspace admin that works across every organization in the workspace. | **Workspace management** > **API tokens**. See [Workspace API tokens](https://docs.coderabbit.ai/api/workspace-api-tokens.md). | | 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](https://docs.coderabbit.ai/api/workspace-api-tokens.md) | 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](https://docs.coderabbit.ai/api/mcp.md), 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 **1. Open API keys** In the CodeRabbit app, open **API keys** for the [US region](https://app.coderabbit.ai/settings/api-keys) or the [EU region](https://app.eu.coderabbit.ai/settings/api-keys). Organizations on a self-managed Git provider or on self-hosted CodeRabbit find the page at `/settings/account/api-keys`. **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-`. **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](https://docs.coderabbit.ai/management/custom-roles.md). * **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](#select-an-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](https://docs.coderabbit.ai/api/reference/security-scans-code-list.md) at `/v1/security/scans/code` and [Bug Scan findings](https://docs.coderabbit.ai/api/reference/bug-scan-findings-list.md) 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](#select-an-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](#select-an-organization). 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](https://docs.coderabbit.ai/api/reference/request-pull-request-review.md) needs an agentic key, because the review uses its owner's seat. * In an Enterprise SSO workspace, [listing users](https://docs.coderabbit.ai/api/reference/list-users.md) and [managing seats](https://docs.coderabbit.ai/api/reference/manage-seats.md) need a workspace API token. User and agentic keys get `403 SSO_WORKSPACE_ORG_KEY_FORBIDDEN`. * [Adding users](https://docs.coderabbit.ai/api/reference/add-users.md) and [changing the seat assignment mode](https://docs.coderabbit.ai/api/reference/update-seat-assignment-mode.md) 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](https://docs.coderabbit.ai/api.md#availability) for plans and Git platforms. ## Send the key Send the key in the `x-coderabbitai-api-key` header over HTTPS: ```bash theme={null} 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](https://docs.coderabbit.ai/api/conventions.md#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](https://docs.coderabbit.ai/api/cli.md). ## 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](https://docs.coderabbit.ai/api/workspace-api-tokens.md#supported-operations) 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](https://docs.coderabbit.ai/api/reference/change-roles.md) 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](https://docs.coderabbit.ai/api/reference/get-me.md) returns in `scope.id`. See [Identifiers](https://docs.coderabbit.ai/api/conventions.md#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](https://docs.coderabbit.ai/management/custom-roles.md). 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](https://docs.coderabbit.ai/api/mcp.md) 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 > [card] [Handle responses](https://docs.coderabbit.ai/api/conventions.md) > > Learn the base URLs, identifiers, pagination, errors, and rate limits shared by every operation. > [card] [Use workspace API tokens](https://docs.coderabbit.ai/api/workspace-api-tokens.md) > > Create one token that works across every organization of an Enterprise SSO workspace. > [card] [Connect an MCP client](https://docs.coderabbit.ai/api/mcp.md) > > Set up the hosted MCP server with OAuth in Claude, Codex, or another client. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.