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#
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.
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.
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.