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

# Authentication

> API keys, the one header every call sends, and what a refusal looks like.

Every public operation authenticates with an API key created in the
dashboard. The plaintext key is shown once, at creation; Audivo stores only a
hash and cannot show it again.

```http theme={null}
Authorization: Bearer hk_live_...
```

That is the only credential the public API accepts. There is no query
parameter and no `x-api-key` header; the edge answers `401` without reaching
a handler when the header is absent or malformed.

## What a refusal looks like

```json theme={null}
{
  "error": {
    "type": "unauthenticated",
    "code": "unauthenticated",
    "message": "This request carried no Authorization header. Send Authorization: Bearer hk_live_... with every request.",
    "doc_url": "https://docs.audivo.dev/errors#unauthenticated",
    "request_id": "req_...",
    "retryable": false
  }
}
```

Every error the API returns has this shape — see [Errors](/errors).

## Keys, accounts and credits

* A key belongs to one account and carries that account's plan. Credits are
  the account's, never the key's; revoking a key moves no credits.
* Keys are revoked from the dashboard. A revoked key stops working within the
  authorizer's cache window, which is short; the dashboard states the number.
* The dashboard itself signs in with a session, not an API key, and its
  operations refuse an API key. The two never interchange.

## Headers on every response

| header              | meaning                                                                                                                           |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `X-Request-Id`      | Quote it when you report a problem. Refusals generated at the edge carry the gateway's own hyphenated id after the `req_` prefix. |
| `X-RateLimit-Limit` | Your plan's requests per minute. A request over it is answered `429 rate_limited` with `Retry-After`.                             |