> ## 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 API keys and the bearer scheme work.

## Where to get a key

Create and manage your API keys at
[platform.usecroma.com](https://platform.usecroma.com). Sign in, open your
organization, and generate a key from the API keys section. The full key is
shown only once at creation, so copy it somewhere safe before leaving the page.

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

## Bearer scheme

Send your key in the `Authorization` header using the `Bearer` scheme:

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

## Organization-scoped keys only

Croma keys are minted for an **organization**, not an individual user. The API
rejects personal keys 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."
  }
}
```

This keeps usage, rate limits, and billing attributed to the org rather than
whichever teammate happened to create the key.

## Key format

Keys are issued branded as `croma_<env>_…`. For example, `croma_live_…` in
production and `croma_test_…` elsewhere. The environment prefix tells you at a
glance which deployment a key targets; never use a `test` key against
production data or vice versa.

<Warning>
  A key grants full API access for its organization. Store it as a secret
  (environment variable / secrets manager), never commit it, and rotate it if
  exposed.
</Warning>

## Failed authentication

Every authentication failure returns a `401` with an `authentication_error`
envelope. The `code` field 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 or has expired. | Send a valid key as `Authorization: Bearer <key>`, or issue a new one.                      |
| `personal_api_key_not_allowed` | A personal key was used where only organization keys are accepted.                         | Use an organization-scoped key from [platform.usecroma.com](https://platform.usecroma.com). |

<Card title="Next: Rate limits" icon="gauge" href="/rate-limits">
  How quotas are bucketed and surfaced in every response.
</Card>