# Authentication

> How to send your API key, how keys are stored, and how to rotate one.

Section: Get started
Source: https://statementbear.com/docs/authentication
Product: StatementBear statement parsing API, $0.49 per document, 25 free.

---

Send your key as a bearer token. There is no OAuth flow, no signature to compute and no expiry to refresh.

## The header

```http
POST /api/v1/documents HTTP/1.1
Host: statementbear.com
Authorization: Bearer sb_live_9f2c41d0a7b34e58c6d1f0a2b8e37c94
Content-Type: application/pdf
```

A request with no `Authorization` header returns `401 missing_key`. An unknown or revoked key returns `401 invalid_key`.

## Key format

`sb_live_` followed by a long random string. The prefix makes a key recognisable in a log, a paste or a secret scanner, and lets us answer a support question without seeing the rest of it.

## How keys are stored

Hashed. The full key is shown once, when it is created. We cannot read it back to you, so a lost key means issuing a new one.

> **Keep keys server side**
>
> A key has no scope and no origin restriction. Keep it in your backend and your secret store. Never ship it to a browser, a mobile app or a customer's device.

## Rotating and revoking

- Hold more than one key at a time. Issue the new key, deploy it, then revoke the old one.
- Revocation applies to the next request. Nothing is cached.
- A revoked key is kept rather than deleted, so past usage stays attributable on your invoice.
- Issue and revoke keys yourself in the [console](https://statementbear.com/dashboard/api).

## There is no test mode

No `sb_test_` key, no sandbox host and no fixture responses. Your first 25 documents are free against the live endpoint, so the code you evaluate with is the code that ships.

## Authentication errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `missing_key` | No `Authorization` header. |
| 401 | `invalid_key` | Unknown, malformed or revoked key. |
| 402 | `canceled` | The key is valid but billing was cancelled. Keys are kept, so reactivating needs no redeploy. |

None of these are charged or count against your monthly cap. Full list on [Errors](https://statementbear.com/docs/errors).

---

All documentation: https://statementbear.com/docs/llms.txt
Questions: api@statementbear.com