Authentification et portées
La clé
Une clé d'API est une chaîne de la forme hela_live_<40 caractères> ou hela_test_<40 caractères>. Elle s'envoie dans l'en-tête Authorization :
Authorization: Bearer hela_live_3f9c…
Hela ne stocke que l'empreinte SHA-256 de la clé. Elle est affichée une fois, à la création ; perdue, elle se révoque et se recrée. La liste des clés ne montre que le préfixe (hela_live_3f9c) pour la reconnaître.
Production et test
hela_live_ |
hela_test_ |
|
|---|---|---|
| Lecture | données réelles | données réelles |
| Écriture | oui | refusée — 403 avec le code forbidden |
| Limite | 600 req/min | 60 req/min |
| Webhooks | reçoit les événements | reçoit les événements |
Une clé de test est la bonne clé pour développer : vous voyez vos vraies ventes, vous ne pouvez rien casser. Passez en production quand votre programme écrit.
Les portées
Une clé porte des portées, qui sont les permissions du produit. La liste complète est renvoyée par GET /companies/{id}/api-keys dans scopes ; en voici l'essentiel.
| Module | Portées |
|---|---|
| Tableau de bord | dashboard:view |
| Ventes | sales:view, sales:create, sales:update, sales:cancel, sales:refund |
| Achats | purchases:view, purchases:create, purchases:update |
| Stock et catalogue | inventory:view, inventory:update, items:create, items:update |
| Partenaires | partners:view, partners:create, partners:update |
| Trésorerie | wallets:view, transactions:create, transfers:create |
| Rapports | reports:view, exports:create |
| Événements et webhooks | events:read, webhooks:manage |
| Intégrations | integrations:manage |
Trois portées n'existent que pour les clés : events:read (lire le journal des événements), webhooks:manage (créer et gérer des webhooks — c'est ce que font Zapier et n8n), exports:create (lancer un export).
Quelques permissions ne peuvent jamais être données à une clé, parce qu'elles touchent aux personnes ou à l'argent du compte : settings:members, settings:roles, developers:manage, billing:*. Une tentative renvoie 400 scope-not-allowed:<portée>.
Ce qu'une clé voit
Une clé agit au nom de l'entreprise, pas d'une personne. Dans l'historique des documents, l'auteur apparaît comme « Clé API actor.kind = "api_key".
Une clé n'a pas de restriction d'établissement : elle voit toute l'entreprise. Si vous avez besoin d'une vue par boutique, filtrez (?businessUnitId=).
Révoquer
DELETE /companies/{id}/api-keys/{keyId} ou le bouton de la page Développeurs. Effet immédiat ; la prochaine requête reçoit 401. Les webhooks créés avec cette clé restent en place : ce sont des objets de l'entreprise, pas de la clé.
Bonnes pratiques
- Une clé par usage. « Zapier » et « Site » séparées : révoquer l'une ne casse pas l'autre.
- Jamais de clé côté navigateur ou dans une application mobile distribuée. Le serveur qui appelle Hela doit être à vous.
- Faites tourner les clés qui ont pu fuiter : créer la nouvelle, basculer, révoquer l'ancienne. Aucune interruption.