Guide

Foyers

Un foyer est l'unité d'isolement : comptes, transactions, budgets, catégories, règles et clés appartiennent à un seul. Votre clé aussi : voici ce qu'elle permet, et ce qu'elle ne permet pas.

Un foyer, un périmètre étanche

Toutes les ressources financières de l'API résident dans un foyer et s'adressent sous /households/:householdId/…. Une personne peut appartenir à plusieurs foyers avec un rôle différent dans chacun (propriétaire, éditeur ou lecteur) : la colocation, la maison familiale et une activité annexe restent ainsi séparées dans un même compte.

Les foyers ne partagent jamais de données. Pas de lecture entre foyers, pas de liste de catégories commune, aucune opération de copie depuis un autre foyer. Seule la personne circule.

Votre clé est liée à un foyer

Une clé est créée dans un foyer et ne peut agir que sur celui-ci ; une requête visant un autre foyer est rejetée avec 403, même si son propriétaire y a accès dans l'application. Pas besoin de connaître l'id : le segment littéral current résout toujours vers le foyer de la clé.

Dans quel foyer se trouve cette clé ?

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"

Ce qu'une clé ne peut pas faire

Le cycle de vie du foyer et l'appartenance sont réservés à la session : une personne connectée dans l'application, jamais une clé API. Ces appels renvoient 403 API_KEY_NOT_ALLOWED :

POST /households: créer un foyer
GET /households: lister les foyers dont vous faites partie
DELETE /households/{householdId}: supprimer un foyer
Invitations : envoyer, accepter et révoquer
Membres : lister, changer de rôle, retirer, quitter
Transférer la propriété et revenir à la configuration initiale

La raison tient au rayon d'impact : une clé qui fuite inquiète déjà bien assez à l'intérieur d'un foyer, sans pouvoir en plus en créer d'autres ou énumérer tous ceux de son propriétaire. L'exception est GET /households/current, qui demande read:households et permet à une intégration de savoir où elle se trouve.

json

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

Limites de propriété

Vous pouvez appartenir à un nombre illimité de foyers, mais vous ne pouvez en POSSÉDER qu'un nombre limité : 2 en offre gratuite et 10 en Pro. Créer au-delà du plafond (depuis l'application, la création étant réservée à la session) renvoie 409. Besoin de plus ? Écrivez-nous et nous relèverons la limite.

json

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

Démarrer un foyer

Un nouveau foyer est créé vide, avec une langue de données (`locale`, par défaut la langue d'interface de la personne qui le crée). GET /meta/category-packs?locale=&dataLocale= liste les packs de départ avec les groupes et catégories exacts que chacun crée (libellés en `locale`, noms en `dataLocale`), et POST /households/:householdId/starter-pack en applique un avec write:categories dans la langue de données du foyer. L'application est idempotente par nom : réessayer ne duplique jamais la structure.