Authentication

Authenticate every request with a secret key in the Authorization header:

Authorization: Bearer bd_test_4eC39HqLyjWDarjtT1zdp7dc

Requests without a valid key fail with 401 and one of these codes:

Code	Meaning
missing_api_key	No Authorization: Bearer … header was sent.
invalid_api_key	The key doesn’t exist or is malformed.
api_key_expired	The key passed its expiry date. Create or roll a new one.
api_key_revoked	The key was revoked in the dashboard.

Keep keys secret

Keys can create documents and email your customers. Use them only from your server. Never put them in a browser, a mobile app or a public repository. The API doesn’t accept browser (CORS) requests, so a key in front-end code won’t work anyway.

Creating keys

Create keys in the dashboard under Developers → API keys. Each key has:

• A name, so you know where it’s used (e.g. “Production server”).
• An environment: sandbox or production. Production keys require a verified business and your password.
• Access: full access, or a restricted set of scopes.
• An optional expiry: 30, 90 or 365 days.

The full key is shown once, when you create it. Brrndops stores only a hash, so a lost key can’t be recovered: roll it instead.

Restricted keys and scopes

Give each system only the access it needs. A key used only to download PDFs, for example, needs just pdf:generate.

Scope	Allows
invoices:read	List and retrieve invoices
invoices:write	Create, update, delete and send invoices
pdf:generate	Download invoice PDFs

invoices:* grants both read and write. A key with no scopes has full access. Calling an endpoint outside a key’s scopes returns 403 insufficient_scope.

Rotating keys

To rotate a key without downtime, use Roll key in the dashboard. You get a new key with the same name and access, and choose how long the old one keeps working: immediately, 24 hours or 7 days. Deploy the new key, then let the old one expire.

If a key may have leaked, roll it with Immediately, then check Request logs for unexpected activity.