Guide

Households

A household is the tenant: accounts, transactions, budgets, categories, rules and keys all belong to exactly one. Your key belongs to one too, here is what that lets you do, and what it does not.

One tenant, one household

Every financial resource in the API lives inside a household and is addressed under /households/:householdId/…. A person can belong to several households with a different role in each (owner, editor or viewer), which is how a shared flat, a family home and a side business stay apart in one account.

Households never share data. There is no cross-household read, no shared category list and no copy-from-another-household operation. The only thing that crosses is the person.

Your key is bound to one household

A key is minted inside a household and can only ever act on that one; a request aimed at another household is rejected with 403 regardless of what its owner can reach in the app. You do not need to know the id: the literal segment current always resolves to the key's own household.

Which household is this key in?

bash

curl -H "Authorization: Bearer vokse_sk_…" \     https://api.vokse.ai/households/current

bash

# every scoped route takes the alias in place of the idcurl -H "Authorization: Bearer vokse_sk_…" \     "https://api.vokse.ai/households/current/transactions?limit=50"

What a key cannot do

Household lifecycle and membership are session-only, a signed-in person in the app, never an API key. These return 403 API_KEY_NOT_ALLOWED:

POST /households: create a household
GET /households: list the households you belong to
DELETE /households/{householdId}: delete a household
Invitations: send, accept and revoke
Members: list, change role, remove, leave
Transfer ownership and reset to onboarding

The reasoning is blast radius: a leaked key already worries you enough inside one household without also being able to mint new ones or enumerate every household its owner belongs to. GET /households/current is the exception and needs read:households, it is how an integration discovers where it is.

json

{  "error": {    "code": "API_KEY_NOT_ALLOWED",    "message": "This endpoint is not available to API keys."  }}

Ownership limits

You may belong to unlimited households, but you may only OWN a limited number: 2 on the free plan and 10 on Pro. Creating past your ceiling (from the app, since creation is session-only) returns 409. Need a higher limit? Get in touch and we will raise it on your plan.

json

{  "error": {    "code": "HOUSEHOLD_LIMIT_REACHED",    "message": "You already own 2 households, the maximum for your plan.",    "details": { "limit": 2, "owned": 2 }  }}

Starting a household off

A new household is created empty, with a data language (`locale`, defaults to the creator's UI language). GET /meta/category-packs?locale=&dataLocale= lists the starter packs with the exact groups and categories each one creates (labels in `locale`, names in `dataLocale`), and POST /households/:householdId/starter-pack seeds one with write:categories in the household's data language. Applying is idempotent by name, so a retry never duplicates the structure.