Authentification

Envoyez votre clé dans l'en-tête Authorization à chaque requête. Les clés sont préfixées par vokse_sk_ afin d'être faciles à repérer dans les journaux (traitez-les comme des mots de passe, ne les versionnez jamais).

Authorization: Bearer vokse_sk_3f8a…

Ouvrez Paramètres → Clés API dans l'application vokse et créez une clé. Le secret ne s'affiche qu'une seule fois, au moment de la création : copiez-le immédiatement. Attribuez à chaque intégration sa propre clé afin de pouvoir en révoquer une sans casser les autres.

1. Allez dans Paramètres → Clés API.
2. Cliquez sur « Créer une clé » et nommez-la d'après l'intégration.
3. Sélectionnez les scopes minimaux dont l'intégration a besoin.
4. Copiez le secret : il n'est affiché qu'une seule fois.

Chaque clé est créée au sein d'un seul foyer et ne peut agir que sur lui. Les routes de l'API portent l'id du foyer dans le chemin, mais vous n'avez presque jamais besoin de le chercher : le segment littéral current se résout toujours vers le foyer de votre clé. Récupérez l'id réel une fois si besoin :

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

Tous les exemples de cette référence utilisent current : ils s'exécutent tels quels avec votre clé. Vous préférez l'id explicite ? Copiez-le depuis Paramètres → Membres dans l'app, ou envoyez-le dans l'en-tête X-Household-Id plutôt que dans le chemin.

Chaque clé porte un ensemble de scopes. Une requête n'est autorisée que si la clé détient le scope exigé par l'endpoint (indiqué par le badge de scope sur chaque endpoint). Les scopes se répartissent en trois classes :

• read:* : accès en lecture seule à une ressource (sûr, idempotent).
• write:* : création, mise à jour et suppression sur une ressource.
• ai:* : invocation des fonctionnalités d'IA ; elles sont décomptées de votre quota mensuel.

Une date d'expiration peut être attribuée à une clé lors de sa création. Passé cette date, les requêtes échouent avec API_KEY_EXPIRED. Effectuez la rotation des clés en en créant une nouvelle, en la déployant, puis en révoquant l'ancienne, sans interruption forcée. Les clés révoquées cessent de fonctionner immédiatement.