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

# Authentication

> How Ciarem API keys work: org-bound, Scale plan or free trial, instantly revocable.

## API keys

* Keys belong to your **organization**, not to a person. They keep working if the teammate who created them leaves.
* The secret starts with `oak_` and is shown **once** at creation. Ciarem stores only a hash — nobody, including Ciarem, can recover a lost secret.
* Send it as a bearer token on every request:

```bash theme={null}
-H "Authorization: Bearer oak_YOUR_SECRET"
```

## Plan requirement

The API is part of the **Scale plan**, and it is open during the **free trial** so you can build and test your integration before you pay. A trial key gets the whole API on a smaller budget — see [rate limits](/api-reference/errors-limits-pagination#rate-limits). `GET /v1/me` tells you which one you are on: `"trial": true` while the trial runs.

When a key is refused with `403`, the `detail` says what fixes it:

| `detail`                | Meaning                                                          | What to do                                                                                                               |
| ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `scale_plan_required`   | The organization is on a live plan below Scale (Solo or Growth). | Upgrade to Scale in **Settings → Billing**. The same key starts working the moment the plan changes — no new key needed. |
| `trial_expired`         | The free trial ended without a payment method.                   | Subscribe to Scale in **Settings → Billing**.                                                                            |
| `subscription_required` | The subscription is canceled, or suspended for non-payment.      | Re-subscribe, or settle the outstanding balance.                                                                         |

## Revocation

Revoke a key any time in **Settings → API keys**. Revocation is **immediate**: the next request with that secret fails with `401`. Admins can create as many keys as they need — one per integration is a good habit, and each key's **last used** date helps you spot the ones you can retire.

## Good practices

* Store secrets in your secret manager or environment variables — never in code or client-side apps.
* The API is server-to-server: don't call it from a browser or mobile app where the key would be exposed.
* Rotate by creating a new key, switching your integration over, then revoking the old one.