Authentication

API keys with scopes, two environments, and per-key rate limits.

API keys

Keys are shown once at creation and stored hashed. Pass them as a Bearer token:

Authorization: Bearer brivio_sk_live_...

Live vs test

brivio_sk_live_… keys operate on your real organization. brivio_sk_test_… keys operate on a paired sandbox organization that is provisioned automatically on first use — fully isolated data, no ANAF/e-Factura submissions, no external side effects. Ideal for CI and development.

Scopes

Each key carries explicit scopes like invoices:read, invoices:write, efactura:submit, webhooks:write. Requests without the required scope get 403 SCOPE_REQUIRED. Grant the minimum you need.

Rate limits

Default 60 requests/minute per key (configurable per key). Responses include X-RateLimit-Remaining; a 429 includes Retry-After. The official SDKs retry 429/5xx automatically with exponential backoff.

Key rotation

Rotate a key with POST /v1/api-keys/:id/rotate — you get a replacement key with the same scopes while the old key stays valid for a grace period (default 24h, configurable 0–72h) for zero-downtime cutover.

curl -X POST https://api.brivio.ro/v1/api-keys/KEY_ID/rotate \
  -H "Authorization: Bearer brivio_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "grace_period_hours": 24 }'

Errors

{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}