Authentication

Every /v1/* request is authenticated with an org-scoped API key passed as a bearer token.

Key formats

Format	Mode	Where to use
`ak_live_…`	Live	`api.adevapro.com.au` only
`ak_test_…`	Test	`sandbox.adevapro.com.au` only

Keys never cross modes. Presenting a wrong-mode key returns 401 at the auth layer — before any business logic runs.

Bearer scheme

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

We only ever store a SHA-256 hash + 16-char display prefix. Lose the secret → mint a new key, revoke the old one.

Scopes

debts:read, debts:write, debts:documents:write
debtors:read, debtors:write
payments:read, transactions:read
branding:read, branding:write
webhooks:read, webhooks:write

Missing the required scope → 403. Read-only keys reject all :write scopes regardless.

Rotation

Mint new → roll out → revoke old. No in-place rotation by design — overlapping keys are how you achieve zero-downtime swaps.

Rate limits

Defaults: live keys 1000 req/h + 20000 req/d; test keys 3600 req/h + 50000 req/d. On 429 we include Retry-After, X-RateLimit-Limit/Remaining/Reset.