# Authentication

Every request carries an API key as a bearer token.

```sh
curl https://api.bighugger.com/v1/search?q=embedding+models \
  -H 'authorization: Bearer bh_live_...'
```

Every call to `api.bighugger.com` carries a key. The key identifies the account the call is billed
to, and billing is per call rather than per seat, so there is no shared or unattributed
credential.

## Keys

Keys are created and revoked from your account, and a key is shown once at creation. We store only
a hash of it, which means a lost key is replaced rather than recovered. Revocation takes effect on
the next request; there is no cached-credential window to wait out.

Use a separate key per deployment. It costs nothing, it makes usage legible per environment, and
it means rotating a key that leaked from a staging box does not take production down with it.

## Scopes

A key carries scopes, and a scope is checked before any work starts. A key without the scope for
an endpoint is refused outright rather than served a reduced result — a quiet downgrade is the
failure mode that gets discovered in production, weeks later, as missing data.

| Scope | What it permits |
| --- | --- |
| `search` | Querying the index |
| `chat` | Asking a question and receiving an answer with sources |
| `workbooks` | Creating and downloading packed artifacts |
| `models` | Requesting and reading cached model files |

Ask for the narrowest set that does the job. A key used only by a retrieval service has no reason
to be able to spend an account's balance on agent runs.

## Agents and devices

A process without a browser can obtain a key through the device flow: request a code, show it to
whoever is authorising, then exchange it for a key. The exchange is one-time, so a code captured
from a terminal is worth nothing after it has been used.

Never ship a key inside a client that a user can read. Anything running on someone else's machine
should call your server, which holds the key.