Autorisation et jetons

L'API publique s'authentifie via des jetons d'accès personnels (PAT). Un jeton est lié à un compte et s'applique à toutes vos entités du constructeur dans les limites des portées accordées.

Création d'un jeton

Un jeton personnel se crée dans l'espace personnel, dans la section des jetons personnels. La valeur du jeton n'est affichée qu'une seule fois lors de la création — conservez-la en lieu sûr. Sur le serveur, le jeton n'est stocké que sous forme hachée et ne peut pas être récupéré ; en cas de perte, émettez-en un nouveau et supprimez l'ancien.

Tous les jetons personnels commencent par le préfixe mbp_.

Transmission du jeton

Le jeton est transmis dans chaque requête via l'en-tête HTTP Authorization selon le schéma Bearer :

Authorization: Bearer mbp_VOTRE_JETON

Le même en-tête est utilisé pour l'accès en session depuis l'espace web (un JWT de courte durée de vie), mais pour les intégrations, utilisez le jeton personnel mbp_….

Portées (scopes)

Un jeton possède un ensemble de portées au format ressource:action. La lecture nécessite le suffixe :read, les modifications :write. Portées disponibles :

  • bots:read, bots:write — bots, leurs paramètres, synchronisation, jeton du bot.
  • reactions:read, reactions:write — réactions, import, test de formules, liens, ordre.
  • labels:read, labels:write — étiquettes des abonnés.
  • collections:read, collections:write — collections et enregistrements.
  • flows:read, flows:write — scénarios.
  • integrations:read, integrations:write — intégrations, connexions, identifiants.
  • media:write — téléversement dans la bibliothèque de médias.
  • templates:read, templates:write — modèles de bots.
  • settings:read, settings:write — paramètres.
  • subscribers:read — abonnés et historique de dialogue (lecture).
  • broadcasts:write — diffusions et leur gestion.
  • stats:read — statistiques et analytique.
  • billing:read — solde et forfaits (lecture).

La portée spéciale * donne un accès total à l'ensemble des endpoints publics.

Ce qui est accessible ou non avec le jeton

Avec un jeton personnel, seuls les endpoints du constructeur sont accessibles — ceux qui « aident à construire le bot ». Non accessibles via PAT (uniquement depuis une session web) : connexion et inscription, endpoints mobiles, paiement et rechargement du solde, notifications, journal d'audit, envoi de messages en tant qu'opérateur dans un dialogue, webhooks entrants et callbacks de paiement, WebSocket. Une requête avec un jeton mbp_ vers une telle route renverra 401 ou 403.

Si le jeton ne dispose pas de la portée requise pour une route donnée, une réponse 403 est renvoyée. Pour plus de détails sur les codes, consultez le guide des erreurs.

Pour aller plus loin