The API uses personal API keys as bearer tokens. Keys are tied to your Kualia account and can act on every workspace your account has access to (including family-shared workspaces).
Creating a key
- Open the web app and go to Settings → API Keys.
- Click Create Key, give it a name, and optionally mark it Read-only.
- Copy the key immediately — it is shown exactly once and never again. Kualia stores only a hash of it.
You can have up to 20 active keys. Use separate keys per integration so you can revoke one without breaking the others.
Using a key
Send the key in the Authorization header of every request:
A missing or invalid key returns 401 unauthorized.
Scopes
| Scope | Granted by | Allows |
|---|
read | Every key | All GET endpoints |
write | Keys created without Read-only | All POST, PATCH, and DELETE endpoints |
403 forbidden.
Revoking a key
In Settings → API Keys, click Revoke next to a key. Revocation is immediate and permanent — requests with that key start failing with 401 right away.
Treat API keys like passwords. Anyone who has a key can read and change your budget data. Never commit keys to source
control or share them in messages.
Rate limits
Each key may make 200 requests per hour (fixed window). Exceeding the limit returns 429 rate_limit_exceeded with a Retry-After header (seconds until the window resets).
Review status of API writes
Transactions created through the API land in the in-app review queue (review_status: "needs_review") by default, so you can verify programmatic writes before treating them as final. Pass "review_status": "reviewed" on create if you want to skip the queue. Updates through the API never silently change a transaction’s review status — it only changes when you send review_status explicitly. 
