# Authentication

> Authenticate API requests with Bearer API keys and manage key lifecycle safely.

## Bearer API keys

Pass your API key in the `Authorization` header on every request to `https://api.kerox.ai/v1`:

```bash
curl https://api.kerox.ai/v1/account \
  -H "Authorization: Bearer $KEROX_API_KEY"
```
```python
import os
import requests

resp = requests.get(
    "https://api.kerox.ai/v1/account",
    headers={"Authorization": f"Bearer {os.environ['KEROX_API_KEY']}"},
    timeout=30,
)
print(resp.json())
```
```javascript
const res = await fetch('https://api.kerox.ai/v1/account', {
  headers: { Authorization: `Bearer ${process.env.KEROX_API_KEY}` },
});
console.log(await res.json());
```

`GET /v1/models` and `GET /v1/models/{id}` can be called without a key to inspect public rates and schemas. Passing your key returns your account's effective pricing (including any account-level or model-specific discount).

## Key security & rotation

- **Hashed at rest**: Kerox only stores a cryptographic hash of each key. The full key is shown once, when you create it in [Console → API → API keys](/console/api-keys).
- **Server-side only**: Do not embed live API keys in client-side browser apps or mobile binaries.
- **Zero-downtime rotation**: Create a new key, deploy it to your services, verify traffic on the new key in the console, and then revoke the old key. A revoked key is rejected with HTTP `401` (`invalid_api_key`); allow up to a minute for the revocation to reach every server.

## Account prerequisites

Before `POST /v1/tasks` accepts submissions:

1. Your email address must be verified, which signing in with an emailed code or with Google does (otherwise HTTP `403` `email_not_verified`).
2. Your account must be active (otherwise HTTP `403` `account_disabled`).
3. Your available wallet balance must cover the estimated task cost (otherwise HTTP `402` `insufficient_balance`).
