Authentification

FreeMaint accepte deux mécanismes d'authentification : les JWT (émis par /auth/login, utilisés par nos applications Web et mobiles) et les clés API (créées dans /company-settings/api, utilisées par vos propres intégrations).

JWT (sessions utilisateur)

1. POST /auth/login — Corps : {email, password}. Renvoie {access_token, refresh_token}.
2. Envoyer l'en-tête Authorization — À chaque requête : Authorization: Bearer <access_token>.
3. Actualiser une fois expiré — POST /auth/refresh avec le refresh_token pour obtenir un nouvel access_token. Les jetons d'accès durent 2 heures.

Clé API (intégrations de serveur)

1. Ouvrez /company-settings/api ou /profile/api-keys — Les administrateurs créent les clés dans Paramètres de l'entreprise > API, à partir de l'offre Business. Une personne dont le rôle dispose de l'autorisation « Créer des clés API personnelles » crée les siennes sous Profil > Sécurité > Clés API. Un rôle doté de la permission « Gérer les intégrations » (par exemple le modèle Administrateur des intégrations) peut créer, révoquer et supprimer les clés de l'entreprise sans être administrateur ; seul un administrateur confie une clé à une autre personne.
2. Cliquez sur "Nouvelle clé" — Définissez éventuellement une date d'expiration et un niveau d'accès (Lecture seule par défaut). La clé brute n'est affichée qu'UNE FOIS — copiez-la immédiatement.
3. Utilisez-le — Envoyez Authorization: Bearer fmk_<rawKey> à chaque requête. Format : commence par fmk_ suivi de 32 caractères hexadécimaux.

Notes de sécurité

• Les clés API sont stockées sous forme de hachages SHA-256 : une fois que vous fermez la boîte de dialogue de révélation, la valeur brute est irrécupérable
• La révocation d'une clé la désactive immédiatement ; la ligne est conservée pour audit
• Chaque clé appartient à une seule entreprise et n'atteint jamais que les données de celle-ci — un enregistrement d'une autre entreprise est tout simplement introuvable
• Les clés peuvent avoir un expiresAt facultatif pour les intégrations de courte durée
• Niveaux d'accès, un plafond qui s'ajoute aux autorisations du propriétaire : READ (par défaut — requêtes seules), READ_STOCK (requêtes + adjustStock — idéal pour une borne de consommation), FULL (toutes les opérations que le rôle du propriétaire autorise)
• Chaque clé agit en tant que son propriétaire : chaque appel porte ses autorisations et sa visibilité sur les données, et ce qu'elle écrit est signé de son nom. Si le propriétaire est désactivé, la clé est refusée (401, code API_KEY_OWNER_INACTIVE) jusqu'à ce qu'un administrateur la confie à une autre personne dans Paramètres de l'entreprise > API — la valeur de la clé ne change pas.

Tester une intégration

Il n'existe pas d'environnement de test séparé : une clé d'API s'adresse toujours aux données réelles de l'entreprise à laquelle elle appartient. Deux façons de tester sans risque. (1) Utilisez une deuxième entreprise comme entreprise de test — l'isolation entre entreprises est le mécanisme même qui sépare tous les clients, donc rien de ce que vous y faites ne peut atteindre vos données de production. Les clés d'API nécessitent l'offre Business : cette entreprise doit donc elle aussi être en Business, une entreprise gratuite ne peut pas en créer. (2) Pour du travail en lecture seule, créez une clé au niveau d'accès READ : elle peut exécuter toutes les requêtes et aucune mutation, elle ne peut donc rien modifier. Quand vous serez prêt à écrire, une clé READ_STOCK autorise adjustStock et rien d'autre.