> ## 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.

## API-key access

`csk_` keys can use either the default all-access setting or a selected set of API capabilities:

* **Default (`NULL`) access** means all-access. The key can use the capabilities available today and automatically receives capabilities added in the future.
* **Selected access** limits the key to the capabilities selected for it. That selection is frozen; future capabilities are not added automatically.

The existing `admin`/`member` setting controls console key-management visibility. It is not endpoint authority: API access is determined by the key's capability scopes.

| Capability group | Scope | Includes |
| - | - | - |
| Search | `search:read` | Search, integration results, and MCP `web_search` |
| Documents | `document:read` | Document reads and MCP `web_fetch` |
| Feedback | `feedback:write` | Feedback writes |
| Deep research runs | `research:write` | Starting, listing, and reading research run results |
| Files | `files:read`, `files:write` | Files knowledge-base read and write operations |
| Usage | `usage:read` | Usage reads |

Calling an endpoint, or an MCP tool, that requires a capability your key does not have returns the existing `403 insufficient_scope` response:

```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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.