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

# Authentication

> API keys, where they come from, and how they behave.

## API keys

Create keys on the **Developers** page in the terminal
([astreus.ai/developers](https://astreus.ai/developers)).
Any account can — the Free plan needs no card.

Send the key on every request, either way:

```bash theme={null}
curl "https://astreus.ai/api/v1/companies/NVDA" \
  -H "X-API-KEY: pk_live_YOUR_KEY"

# equivalent
curl "https://astreus.ai/api/v1/companies/NVDA" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"
```

If both headers are sent, `X-API-KEY` wins.

<Warning>
  A key is shown **once**, at creation. Astreus stores only its SHA-256 hash — a lost key
  cannot be recovered, only rotated.
</Warning>

## Key lifecycle

| Action | Where                 | Effect                                                         |
| ------ | --------------------- | -------------------------------------------------------------- |
| Create | Developers → API Keys | Up to 10 active keys per account                               |
| Rotate | Developers → API Keys | Old key revoked and replaced atomically; new secret shown once |
| Revoke | Developers → API Keys | Permanent; takes effect everywhere within \~60 seconds         |

## Scope of a key

Keys are **data credentials**. They work on every documented data endpoint and are
deliberately rejected (401) on account surfaces: key management, billing, watchlists,
workspace. A leaked data key can never mint more keys or touch the account that owns it.

## OAuth for MCP clients

Connector UIs such as claude.ai never see a key: they authorise through OAuth 2.1 (dynamic
client registration + PKCE, advertised at `/.well-known/oauth-protected-resource/api/mcp`)
and receive an access token with the same data-only scope as a key. Those tokens are
accepted on the MCP endpoint and on the data routes; they are rejected on account surfaces
exactly as keys are. See [MCP server](/mcp-server).

## Tiers

* `public` endpoints (coverage stats, logos, person photos, presentation slide images,
  health) need no credentials.
* Everything else needs a key (or a signed-in terminal session's Cognito ID token — that is
  what the terminal itself uses, but it expires hourly; programmatic access should use keys).
* A `402` with code `upgrade_required` marks a Pro-only surface; none of the documented
  data routes is Pro-only today.