# API authentication

> How Ranqo API keys work, where to send them, which brands a key can read, and what happens when a key expires or is revoked.

Source: https://ranqo.ai/docs/api/authentication

Every request carries an API key. Keys belong to the account, are created by its owner, and can read only the brands they were given.

## Send the key in the Authorization header

```http
Authorization: Bearer ranqo_sk_...
```

The API reads the key from this header and nowhere else: it ignores cookies, so a signed-in browser session cannot call it. Every key starts with ranqo_sk_, which lets secret scanners recognise one that leaks.

Never put a key in a URL. A request whose address contains a key is refused with `api_key_in_url`, because URLs end up in server logs and browser history. If that happens with a real key, revoke it and create another.

## Creating keys

The account owner creates keys in the **API keys** section of [Settings](https://app.ranqo.ai/settings); teammates cannot. Each key has:

- **A name**, shown in Settings and returned by `GET /v1/account`, so you can tell keys apart.
- **Brand access**: every brand, including ones added later, or only the brands you choose. A brand the key cannot read answers `not_found`, exactly as a brand that does not exist.
- **An expiry**: 30, 90, and 365 days, or never.

The number of active keys depends on the plan (see [Rate limits](https://ranqo.ai/docs/api/rate-limits)), and an account can create at most 10 keys an hour.

The key is shown once, when it is created. Settings lists it afterwards only in a shortened form: Ranqo stores a fingerprint of the key, not the key.

## Revoking a key

Revoke a key in Settings the moment you stop using it or suspect it leaked. It stops working on the next request. Revoking is always available, even after a plan ends, so an account can switch off a key it no longer pays for.

## When a key is refused

| Code | Meaning |
| --- | --- |
| `missing_api_key` | No `Authorization` header, or an empty one. |
| `invalid_api_key` | The header does not hold a well-formed Ranqo key, or the key does not exist. |
| `api_key_revoked` | The key was revoked. |
| `api_key_expired` | The key has passed its expiry. |
| `api_key_orphaned` | The account that owns the key has since joined another team. Ask the team's owner to create a key in their Settings. |
| `plan_upgrade_required` | The account's plan does not include API access. |
| `subscription_inactive` | The account's trial or subscription has ended. |

The first five answer `401` with a `WWW-Authenticate` header, the last two `403`. The plan is read on every request, so a change of plan applies at once.

Repeated failures are limited: after 30 failed attempts in a minute, a key is refused with `rate_limited` until the minute is over. Attempts with keys that do not exist are also counted by the address they come from, so guessing keys from one address stops quickly without locking out the keys in use there.

## Keeping keys safe

- Give each tool its own key, restricted to the brands it needs, so revoking one does not break the others.
- Use an expiry, and replace keys before they lapse.
- Keep keys on the server. A key in a web page or a mobile app is readable by anyone who opens it.