Authentification et droits

Envoyer la clé

Chaque appel porte la clé du compte dans l'en-tête Authorization, avec le schéma Bearer :

curl https://api.mabellenote.com/v1/me \
  -H "Authorization: Bearer mbn_live_..."

La clé ne passe jamais dans l'adresse ni dans le corps de la requête. Seules GET /v1/health et GET /v1/openapi.json se passent de clé.

Cycle de vie d'une clé

• Création : dans l'application, Réglages › Intégration, API & webhooks, par un propriétaire ou un administrateur. Chaque création est signalée par email aux propriétaires et aux administrateurs du compte.
• Affichage unique : la clé complète n'apparaît qu'à sa création. Elle n'est jamais récupérable ensuite, même par le support. L'application ne montre que son préfixe visible, par exemple mbn_live_AbC1, qui permet de la reconnaître.
• Portée : une clé couvre tout le compte, c'est-à-dire tous ses établissements, présents et futurs.
• Nombre : un compte a au plus 10 clés actives.
• Expiration : facultative, choisie à la création (30 jours, 90 jours, un an ou jamais). Passé cette date, l'API répond 401 api_key_expired.
• Révocation : immédiate et définitive. L'appel suivant reçoit 401 api_key_revoked.
• Propriété : une clé appartient au compte, pas à la personne qui l'a créée. Elle continue de fonctionner si cette personne quitte le compte, et les propriétaires en sont prévenus.

Les droits

Une clé porte la liste de droits choisie à sa création. L'application propose des modèles : Lecture seule (établissements, avis, statistiques, retours privés), CRM (lecture et base clients), Caisse (établissements, contacts, passages et codes promo) ou Personnalisé. Les droits ne se modifient pas après coup : pour en changer, créez une nouvelle clé, basculez votre intégration dessus, puis révoquez l'ancienne.

Une opération appelée sans le droit qu'elle requiert répond 403 insufficient_scope. Le droit requis par chaque opération figure dans la référence.

Le droit contacts:read donne accès à des données personnelles : coordonnées, consentements et historique de vos clients. Ne l'accordez qu'aux outils qui en ont besoin.

Deux droits demandent davantage qu'une case cochée :

• contacts:write : à la création de la clé, le propriétaire ou l'administrateur certifie que les clients envoyés par l'outil ont donné leur consentement. Le guide des écritures détaille la preuve de consentement.
• replies:publish : il n'a d'effet que pour les établissements qui ont autorisé la publication par l'API dans l'application. Voir la publication sur Google.

Plan et état du compte

• Plan Pro : l'API est incluse dans le plan Pro, et pendant l'essai gratuit. Un compte sans plan Pro effectif reçoit 403 plan_upgrade_required. Ses clés sont conservées et fonctionnent de nouveau, à l'identique, dès le retour au plan Pro.
• Compte en lecture seule : avec un plan Pro effectif, un compte en lecture seule continue de répondre aux lectures et d'envoyer ses webhooks. Les écritures y reçoivent 403 tenant_read_only. Le champ account.readOnly de GET /v1/me indique cet état.

L'API contrôle dans cet ordre : la clé, le plan, l'état du compte pour une écriture, le droit, puis la limite de débit.

Isolation entre comptes

Le compte vient toujours de la clé : aucun chemin ni paramètre ne le désigne. Un identifiant qui appartient à un autre compte répond 404 not_found, exactement comme un identifiant qui n'existe pas.

Vérifier une clé

GET /v1/me répond pour toute clé valide, quel que soit le reste de ses droits. C'est l'appel à utiliser pour tester une connexion depuis votre outil : il renvoie le compte, le plan effectif, le nom, le préfixe, les droits et la date d'expiration de la clé.

Bonnes pratiques

• Créez une clé par intégration, avec un nom explicite : vous saurez laquelle révoquer.
• N'accordez que les droits nécessaires.
• Conservez les clés dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le code.
• Pour remplacer une clé sans coupure, créez la nouvelle, déployez-la, puis révoquez l'ancienne.