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

# Authentication

> Bearer API keys, scopes, and key-handling conventions for the Caesar API.

Caesar uses standard Bearer authentication. [Sign up in the Caesar app](https://app.trycaesar.com), create an API key, and set it in the `Authorization` header:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/search \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime comparison", "max_results": 3}'
```

For a limited time, all accounts receive a \$1,000 starting credit grant after signup.

## API keys

| Property                    | API key behavior                                      |
| --------------------------- | ----------------------------------------------------- |
| Setup                       | Create in the [Caesar app](https://app.trycaesar.com) |
| Rate limit                  | per-key limit, default 100 requests/second            |
| Account attribution         | recorded to your account                              |
| Document access by `doc_id` | account-granted documents                             |

An API key controls four things:

1. **Usage and credits.** Calls are attributed to the account or team that owns the key.
2. **A dedicated rate limit.** Requests are counted per key, not per IP. See [rate limits](/rate-limits).
3. **Account-scoped attribution.** Keyed searches are recorded to your account, and `/v1/feedback` referencing a `search_id` or `doc_id` is checked against that ownership. Your feedback provably belongs to your searches.
4. **Document grants.** `/v1/document` lookups by `doc_id` resolve documents your account has been granted — by appearing in your search results or by a prior direct `canonical_url` lookup.

## Getting a key

<Info>
  Create keys in the [Caesar app](https://app.trycaesar.com). Store the secret once; the full key is only shown at creation time.
</Info>

## Key format

Console-issued keys start with `csk_`. Legacy alpha keys may start with `sk_live_`, followed by a 12-character `key_prefix` and a longer secret. Non-secret key prefixes are safe to display in dashboards and logs to identify a key. The full key is returned exactly once at creation and stored only as a hash; it cannot be retrieved again.

## Scopes

| Scope            | Grants              |
| ---------------- | ------------------- |
| `search:read`    | `POST /v1/search`   |
| `document:read`  | `POST /v1/document` |
| `feedback:write` | `POST /v1/feedback` |

New keys get all three scopes by default. Calling an endpoint your key lacks the scope for returns `403`:

```json theme={"system"}
{
  "type": "error",
  "request_id": "ee314ccd-dbcd-418f-9c6a-f2917c599c67",
  "error": { "code": "insufficient_scope", "message": "API key is not allowed to call this endpoint" }
}
```

## Invalid keys are rejected

Every API request must authenticate. A missing, malformed, unknown, expired, or revoked key returns `401`:

```json theme={"system"}
{
  "type": "error",
  "request_id": "ee314ccd-dbcd-418f-9c6a-f2917c599c67",
  "error": { "code": "invalid_api_key", "message": "missing or invalid API key" }
}
```

## One environment variable everywhere

Every first-party client reads `CAESAR_API_KEY`:

```bash theme={"system"}
# set in your shell profile, or inject it from your secret manager
export CAESAR_API_KEY="$(your-secret-manager get caesar-api-key)"
```

The [Python SDK](/clients/sdks/python) and [TypeScript SDK](/clients/sdks/typescript) pick it up automatically in their constructors, the [CLI](/clients/cli/usage) resolves it after the `--key` flag, and the [MCP server](/clients/mcp/remote) accepts it as a Bearer header. If the variable is unset and no key is stored in client config, API calls fail with `401 missing_api_key`.

## Client attribution: X-Caesar-Client

First-party clients send an attribution header of the form `X-Caesar-Client: cli/0.2.0` (or `python-sdk/0.2.0`, `ts-sdk/0.2.0`). It is a convention, not a contract: the server does not validate or act on it. If you build on the raw API, sending `X-Caesar-Client: yourtool/1.2.3` is encouraged because it helps the Caesar team understand client traffic.

## Key hygiene

<Warning>
  Never paste an API key into a chat, an issue, or a commit. Keys belong in `CAESAR_API_KEY` or your secret manager. The CLI stores keys safely via `caesar-search auth login` — the browser flow mints a named, revocable key straight into the OS keychain, `--device` covers SSH/headless machines, and `--key -` pipes one from a secret manager — and masks them in all output. If a key leaks, contact the Caesar team to revoke it — the key itself cannot be recovered or rotated in place.
</Warning>