# Authentication | Chersus

Documentation

# Authentication

How Chersus API keys work: the Authorization header, key hygiene, and what each error response means when a key is rejected.

Last updated 2026-09-03

You authenticate every Chersus request with a bearer token in the `Authorization` header. No sessions, no cookies, no signatures to compute.

```
curl https://api.chersus.com/v1/run \
-H "Authorization: Bearer chrs_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
  "input": { "type": "text", "value": "Bonjour le monde" },
  "pipeline": [ { "id": "detect", "service": "routing.language.detect" } ]
}'
```

```
const res = await fetch("https://api.chersus.com/v1/run", {
method: "POST",
headers: {
  Authorization: "Bearer chrs_live_YOUR_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  input: { type: "text", value: "Bonjour le monde" },
  pipeline: [{ id: "detect", service: "routing.language.detect" }],
}),
});

const data = await res.json();
```

```
import requests

res = requests.post(
  "https://api.chersus.com/v1/run",
  headers={"Authorization": "Bearer chrs_live_YOUR_KEY"},
  json={
      "input": {"type": "text", "value": "Bonjour le monde"},
      "pipeline": [{"id": "detect", "service": "routing.language.detect"}],
  },
)

data = res.json()
```

## Key format and storage

Keys start with `chrs_live_`, and you see the full key once, at creation. Store it in your secret manager or environment, never in client-side code: the key is the billing identity for every character it processes.

Rotate keys from the dashboard when a key may have leaked. Old keys stop working immediately after rotation, so deploy the new key before rotating.

## When authentication fails

A missing, malformed or revoked key returns `401` with a machine-readable body:

```
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}
```

A `401` from a key that worked yesterday usually means it was rotated. Deploy the new key before rotating, since the old one stops working immediately.

Every other error Chersus returns, including the one you get when the month’s allowance runs out, is in [errors](/en/docs/errors/).