Authentication & API keys

Every request authenticates with a secret API key in the Authorization header:

curl https://api.briefqr.com/v1/operators 
  -H "Authorization: Bearer bqr_live_..."

There are no session cookies and no OAuth. The key is the credential — keep it server-side.

Key prefixes select the mode

Prefix	Mode	Operates on
bqr_live_…	Live	Real operators, devices, sessions — billed
bqr_test_…	Test	An isolated sandbox — never billed

The prefix is authoritative: a live key can only see live data and a test key can only see test data. See test vs live mode.

Scopes

Scope	Can do
read_only	GET requests only
full	Reads and writes (create/update/delete), plus key + webhook management

A write with a read_only key returns 403 insufficient_scope (code: read_only_key).

Minting & revoking keys

Mint keys in the dashboard (Developers → API keys) or via the API with a full key:

curl -X POST https://api.briefqr.com/v1/api-keys 
  -H "Authorization: Bearer bqr_live_..." 
  -H "Content-Type: application/json" 
  -d '{ "name": "CI pipeline", "scope": "read_only", "mode": "live" }'

The response includes the plaintext key once — store it immediately. Afterwards only the last4 is retained; there is no way to reveal it again. Rotate a key by minting a new one and revoking the old:

curl -X DELETE https://api.briefqr.com/v1/api-keys/{id} 
  -H "Authorization: Bearer bqr_live_..."

Revocation is immediate — the next request with that key returns 401.

Failure modes

Situation	Status	error.code
No Authorization header	401	—
Unknown / revoked key	401	—
Expired key	401	expired_key
Write with a read-only key	403	read_only_key

Errors follow the standard envelope.