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

# Authentication

> Authenticate requests with a bearer API key

## Bearer Tokens

Every request must send an API key in the `Authorization` header:

```
Authorization: Bearer cort_your_key_here
```

Cortado API keys always begin with `cort_`. Create one from **Settings > Integrations > API Keys** — see the [API Keys guide](/guides/integrations/api-keys).

```bash theme={null}
curl -H "Authorization: Bearer cort_your_key_here" \
  https://api.cortado.pro/api/v1/ext/contacts/8f14e45f-ceea-467a-9e6a-1f2b3c4d5e6f
```

<Warning>
  Keys are secrets. Keep them on a server or in your automation tool's secrets storage — never in a website, browser extension, or mobile app, where anyone can read them.
</Warning>

## Authentication Failures

| Situation                                                   | Status | `error`               |
| ----------------------------------------------------------- | ------ | --------------------- |
| No `Authorization` header, or it isn't a `Bearer` token     | `401`  | `missing_api_key`     |
| The key is unknown or has been revoked                      | `401`  | `invalid_api_key`     |
| The key is valid but API access is off for the organization | `403`  | `api_access_disabled` |

A revoked key stops working immediately. If API access is turned off for your organization, existing keys are not deleted — they start returning `403` and work again if access is restored.

## Scope

A key can only read data in the organization it was created in. Requesting a record that belongs to a different organization returns `404 not_found`, the same response as a record that doesn't exist — the API never reveals whether another business's record exists.

## Rate Limits

Each key may make **600 requests per minute**. Beyond that, requests return `429` with a `Retry-After: 60` header.

<Tip>
  Cache what you fetch and avoid re-requesting the same record in a tight loop. If you do hit the limit, wait the number of seconds in `Retry-After` before retrying rather than retrying immediately.
</Tip>

## Usage Tracking

Cortado records the last time each key was used and shows it in the keys table under **Last used**. It updates at most once per minute, so a burst of requests shows a single recent timestamp rather than every call.

## Rotating a Key

There is no way to change an existing key's secret. To rotate:

<Steps>
  <Step title="Create a new key">
    Create a second key and copy its secret.
  </Step>

  <Step title="Update your tool">
    Point the integration at the new key and confirm it works.
  </Step>

  <Step title="Revoke the old key">
    Revoke the previous key from the keys table.
  </Step>
</Steps>