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

# Authentication

> Key format, the two accepted headers, why the API is server-to-server, and what rotation and revocation do.

Every `/v1` request carries a Belief Systems API key. Keys look like `belief_live_` followed by a secret, and are minted in the [portal](https://beliefsystems.xyz/data).

## The two headers

`Authorization: Bearer` is the canonical form and the one every example in these docs uses.

<CodeGroup>
  ```bash Authorization theme={null}
  curl -s https://api.beliefsystems.xyz/v1/indices/CONFLICT/latest \
    -H "Authorization: Bearer $BELIEF_API_KEY"
  ```

  ```bash X-API-Key theme={null}
  curl -s https://api.beliefsystems.xyz/v1/indices/CONFLICT/latest \
    -H "X-API-Key: $BELIEF_API_KEY"
  ```
</CodeGroup>

Both carry the same secret and are accepted everywhere. Send one or the other, not both.

<h2 id="keys-belong-on-a-server">
  Keys belong on a server
</h2>

<Warning>
  `/v1` answers cross-origin preflights only for Belief Systems' own origins, so browser JavaScript on your domain will fail. Call it from your backend, which is also where the key belongs: a key shipped to a browser is a published key.
</Warning>

Non-production environments allow `localhost`, so a prototype that works against staging will not work in production. Treat the API as server-to-server from the start.

There is no test mode and no sandbox host. The API is read-only, so a live key is safe to use in development.

## Getting a key

Registration is free: work email, no password, a magic link. An account holds up to **three active keys**, so you can give staging and production their own and tell them apart by prefix in the usage view.

The secret is displayed once, at creation, and is never retrievable. The system stores a hash, not the key. If you lose it, rotate.

## Rotation and revocation

* **Rotation** issues a new secret and retires the old one in the same operation. The old secret stops working immediately. Usage history stays with the account.
* **Revocation** takes effect immediately. Every subsequent call returns [`invalid_api_key`](/api-reference/limits#invalid-api-key).
* Snapshot file downloads validate keys against a one-minute cache, so a revoked key can still open a snapshot file for up to a minute afterward. The API itself does not wait.

Both operations are in the [portal](https://beliefsystems.xyz/data/portal), alongside per-key usage.

## Metering is per key

Rate limits are counted per key, not per IP, so two keys never spend each other's quota. `GET /v1` reports the limits actually in force for the calling key, beside what is left of each window.

<Note>
  Rate limits and the history window are access controls under the [Terms of Service](https://beliefsystems.xyz/terms). Spreading requests across several keys or accounts to exceed them is prohibited. Sustained or production volume is covered by [Index Services](https://beliefsystems.xyz/license).
</Note>

Calls made through the [MCP server](/data-access/mcp-server) draw on the same two windows as direct API calls.