Leitfaden

Haushalte

Ein Haushalt ist die Mandanteneinheit: Konten, Transaktionen, Budgets, Kategorien, Regeln und Schlüssel gehören zu genau einem. Dein Schlüssel auch, hier steht, was das erlaubt und was nicht.

Ein Mandant, ein Haushalt

Alle finanziellen Ressourcen der API liegen in einem Haushalt und werden unter /households/:householdId/… adressiert. Eine Person kann zu mehreren Haushalten gehören, mit je eigener Rolle (Eigentümer, Bearbeiter oder Leser), so bleiben WG, Familienhaushalt und Nebengewerbe in einem Konto sauber getrennt.

Haushalte teilen niemals Daten. Kein Lesen über Haushalte hinweg, keine gemeinsame Kategorieliste, keine Kopieren-aus-anderem-Haushalt-Operation. Nur die Person wechselt.

Dein Schlüssel gehört zu einem Haushalt

Ein Schlüssel entsteht in einem Haushalt und kann nur dort wirken; eine Anfrage an einen anderen Haushalt wird mit 403 abgelehnt, auch wenn sein Besitzer in der App Zugriff hätte. Die ID musst du nicht kennen: Das feste Segment current löst immer auf den Haushalt des Schlüssels auf.

In welchem Haushalt steckt dieser Schlüssel?

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"

Was ein Schlüssel nicht kann

Haushalts-Lebenszyklus und Mitgliedschaft sind sitzungsgebunden: eine angemeldete Person in der App, nie ein API-Schlüssel. Diese Aufrufe liefern 403 API_KEY_NOT_ALLOWED:

POST /households: Haushalt erstellen
GET /households: deine Haushalte auflisten
DELETE /households/{householdId}: Haushalt löschen
Einladungen: senden, annehmen und widerrufen
Mitglieder: auflisten, Rolle ändern, entfernen, verlassen
Eigentum übertragen und Onboarding zurücksetzen

Der Grund ist der Schadensradius: Ein geleakter Schlüssel macht innerhalb eines Haushalts schon genug Sorgen, ohne zusätzlich neue Haushalte anlegen oder alle Haushalte seines Besitzers auflisten zu können. Ausnahme ist GET /households/current mit read:households, damit findet eine Integration heraus, wo sie steht.

json

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

Eigentumslimits

Du kannst unbegrenzt vielen Haushalten angehören, aber nur eine begrenzte Zahl BESITZEN: 2 im kostenlosen Tarif, 10 in Pro. Legst du über dein Limit hinaus an (aus der App, denn das Erstellen ist sitzungsgebunden), kommt 409 zurück. Mehr nötig? Schreib uns, wir heben das Limit in deinem Tarif an.

json

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

Einen Haushalt starten

Ein neuer Haushalt entsteht leer, mit einer Datensprache (`locale`, standardmäßig die Oberflächensprache der erstellenden Person). GET /meta/category-packs?locale=&dataLocale= listet die Startpakete mit genau den Gruppen und Kategorien, die jedes anlegt (Bezeichnungen in `locale`, Namen in `dataLocale`), und POST /households/:householdId/starter-pack legt eines mit write:categories in der Datensprache des Haushalts an. Das Anwenden ist über die Namen idempotent, ein erneuter Versuch dupliziert die Struktur also nie.