Authentication
Send your key as a bearer token. There is no OAuth flow, no signature to compute and no expiry to refresh.
The header#
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#
A prefix 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.
| Prefix | What it does |
|---|---|
sb_live_ | Parses the document you send and bills for it. Counts against your free allowance and your monthly cap. |
sb_test_ | Returns a fixture document. Never billed, never counted. See Test mode. |
How keys are stored#
A live key is hashed. It is shown once, when it is created, and we cannot read it back to you, so a lost live key means issuing a new one. A test key is kept in full and stays on the Keys tab of the console, so you can copy it again whenever you need it.
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.
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.
Something wrong or missing on this page? [email protected]