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

# Authentication

> How to authenticate every request and rotate keys safely.

Every endpoint except `/v1/health` requires an API key. Keys are scoped to a developer account and to a tier (Free or Partner).

## Header

Pass your key as a Bearer token. There is no other supported transport — keys in query strings are rejected with a `400` so they can't end up in server logs or browser history.

```bash theme={"dark"}
curl https://api.elestrals.com/v1/sets \
  -H "Authorization: Bearer $ELESTRALS_KEY"
```

Production keys look like this:

```
elestrals_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The `live_` prefix is meaningful. Any key starting with `elestrals_test_` is reserved for a future sandbox and won't authenticate against the production API today.

## Failure modes

| Status | Code           | What happened                                |
| ------ | -------------- | -------------------------------------------- |
| 401    | `unauthorized` | Missing, malformed, revoked, or unknown key. |
| 400    | `bad_request`  | Key was passed as a query parameter.         |

The error body always includes a `request_id` you can quote in support requests.

## Where to get a key

<Steps>
  <Step title="Sign in to the developer portal">
    Visit [developers.elestrals.com](https://developers.elestrals.com) and sign in. First-time visitors verify their email and accept the Developer Agreement.
  </Step>

  <Step title="Free tier: mint a key">
    From your dashboard, click **Create key**, label it (e.g. `local-dev` or `production`), and copy the raw key shown once at creation.
  </Step>

  <Step title="Partner tier: apply">
    Partner keys are gated by review. Submit an application from the dashboard with your use case and expected volume; approval typically lands within a few business days.
  </Step>
</Steps>

<Warning>
  The portal stores only a SHA-256 hash and a 4-character prefix for UI display. The raw key is shown **once**, at creation. A key you didn't save is a key you have to revoke and replace.
</Warning>

## Rotating a key

Keys don't expire on a schedule. Rotate them when:

* A teammate with access to the key has left.
* A key was committed to a public repo or pasted in a shared chat.
* You want to compartmentalize traffic by environment.

Recommended rotation:

<Steps>
  <Step title="Mint the new key">
    Create a new key with a clear label (e.g. `production-2026-04`).
  </Step>

  <Step title="Deploy with the new key">
    Update your application to read the new key. Keep the old one valid during the rollout so you have a rollback path.
  </Step>

  <Step title="Revoke the old key">
    Once the new key is in production and traffic on the old key has drained — confirm in [Monitor your usage](/monitor-your-usage) — revoke the old key. Revocation is immediate.
  </Step>
</Steps>

A revoked key fails with `unauthorized` on the next request, the same code as an unknown key. The usage dashboard shows the revocation timestamp so you can confirm it took effect.

## Keys are not user identities

Every key represents an *application*, not a person. If you build a tool that exposes Elestrals data to end users, you authenticate to us with one key (yours) and authenticate users to your own application separately. We do not provide user-facing OAuth.