> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How Croma Legal API keys and the bearer scheme work.

## Where to get a key

Keys are created and revoked in the Croma Legal dashboard at
[legal.usecroma.com](https://legal.usecroma.com), under **Desarrolladores**,
tab **Claves de API**. The full key is shown only once at creation, so copy it
somewhere safe before leaving the page. An organization can hold up to **5**
active keys; revoke the ones you no longer use.

<Card title="Create an API key" icon="key" href="https://legal.usecroma.com/developers">
  Open the Croma Legal dashboard to mint and manage your organization's keys.
</Card>

<Note>
  Key management is enabled per user by Croma (every member of the
  organization sees the MCP setup, but only enabled users see the **Claves de
  API** tab). If you need it, ask your Croma contact.
</Note>

## Bearer scheme

Send the key in the `Authorization` header using the `Bearer` scheme, on
every request:

```bash theme={"dark"}
Authorization: Bearer croma_live_xxxxxxxxxxxxxxxxxxxx
```

The same key authenticates the REST API and the [MCP server](/legal/mcp-server):
usage and rate limits are shared between the two.

## Organization-scoped keys only

Keys are minted for an **organization**, not an individual user, and every
request is scoped to that organization: the API never accepts an organization
id from the caller. A personal key is rejected with `401`:

```json theme={"dark"}
{
  "error": {
    "type": "authentication_error",
    "code": "personal_api_key_not_allowed",
    "message": "Personal API keys are not allowed. Use an organization key."
  }
}
```

## Key format

Keys are issued branded as `croma_<env>_…`: `croma_live_…` in production and
`croma_test_…` elsewhere. Legal keys only work against
`api.legal.usecroma.com`; a key from the Croma public-data platform
(`platform.usecroma.com`) is rejected here, and vice versa.

<Warning>
  A key grants read access to your organization's entire portfolio, including
  defendant identification numbers and any data you imported. Store it as a
  secret (environment variable or secrets manager), never commit it, and revoke
  it from the dashboard the moment it may have been exposed. Revocation takes
  effect immediately.
</Warning>

## Failed authentication

Every authentication failure returns `401` with an `authentication_error`
envelope. The `code` tells you what went wrong:

| Code                           | What it means                                                                                                             | How to fix                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `invalid_api_key`              | The `Authorization` header is missing or malformed, or the key was revoked, expired, or belongs to another Croma product. | Send a valid Legal key as `Authorization: Bearer <key>`, or create a new one in the dashboard. |
| `personal_api_key_not_allowed` | A personal key was used where only organization keys are accepted.                                                        | Use an organization key created from the Croma Legal dashboard.                                |

<Card title="Next: Pagination & filters" icon="list" href="/legal/pagination">
  How lists page, which dates mean what, and how to sync incrementally.
</Card>