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

# Authentication

> Bearer-token API keys, test vs live environments, and rotation.

Every API request — except `GET /v1/health` — must include your API key. Two header schemes are accepted:

```http theme={null}
Authorization: Bearer al_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

```http theme={null}
X-API-Key: al_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

Most direct API consumers use `Authorization: Bearer`. The `X-API-Key` header exists for gateway integrations (Smithery, Zapier, Make, n8n) that reserve the `Authorization` header for their own use. If both are present, `Authorization` wins.

## Key format

```
al_<env>_<32-char-random>
```

| Segment | Value |
| - | - |
| Prefix | `al` (literal) |
| Environment | `live` or `test` |
| Random | 32 alphanumeric characters (`a–z`, `A–Z`, `0–9`) |

**Validation regex:** `^al_(live|test)_[a-zA-Z0-9]{32}$`

Keys are stored as a SHA-256 hash. AcreLens cannot recover a lost key — if you misplace it, revoke and replace.

## Live vs test environments

Both environments hit the same routes and return the same shape. The differences are about what gets tracked:

| | Live | Test |
| - | - | - |
| Prefix | `al_live_` | `al_test_` |
| Counts against PAYG balance | ✅ | ✅ |
| Counts against quota / spend caps | ✅ | ✅ |
| Use in CI / dev | discouraged | recommended |
| Use in production | required | not allowed |

> **Note:** Test keys still consume your balance — they're a guardrail against committing live keys to source control, not a free sandbox. Use [free trial reports](/concepts/quota-and-billing#free-reports) for cost-free experimentation.

## Where keys come from

When you verify your account, AcreLens creates one live key and one test key automatically. To create more, open [Manage → API Keys](https://acrelens.com/dashboard/manage/api-keys), click **+ New key**, label it, and pick an environment.

The full key is displayed **exactly once**. Copy it to a secret manager (1Password, AWS Secrets Manager, Doppler, Vercel env vars) before closing the modal.

## Rotating keys

Zero-downtime rotation:

1. Create a new key labeled with today's date (e.g. `Production — 2026-04-28`).
2. Deploy the new key to your application.
3. Once your service has fully rolled over, revoke the old key from [Manage → API Keys](https://acrelens.com/dashboard/manage/api-keys).

Revoked keys return `401 unauthorized` immediately on the next request — there's no grace period. Plan the cut-over so both keys are valid for the few minutes your deploy takes.

## Authorization errors

Any of the following return `401 unauthorized`:

* Missing both `Authorization` and `X-API-Key` headers
* `Authorization` header doesn't start with `Bearer `
* Token doesn't match the format regex
* Token is unknown (never created or fully purged)
* Token has been revoked

Both error and success responses include a `request_id` you can quote when contacting support.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "req_01HY2Z...",
    "retriable": false,
    "docs_url": "https://docs.acrelens.com/errors/unauthorized"
  }
}
```

Only accounts in `ACTIVE` or `TRIAL` status can transit a valid key. Any other status (e.g. `CANCELED`, `PAST_DUE`) returns `403 forbidden` regardless of key validity. Update billing in the [Billing](https://acrelens.com/dashboard/billing) section or contact support.

REST API access is a **Pro-plan feature.** A key belonging to a Free or Starter subscription account is rejected with `403 api_access_required`; upgrade to Pro to use the API. (Legacy pay-as-you-go accounts keep API access.)

## Security checklist

* Store keys in environment variables — **never** commit them to source control.
* Use a secret manager for production keys (1Password, AWS Secrets Manager, Doppler).
* Rotate keys when team members leave or after any suspected exposure.
* Use separate keys per environment and per service (label them descriptively).
* Treat `al_test_` keys with the same care as live keys — they still bill against your account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.