Authentifizierung und Tokens

Die öffentliche API authentifiziert sich über persönliche Zugangstoken (PAT). Ein Token ist an ein Konto gebunden und gilt für alle Ihre Konstruktor-Entitäten innerhalb der gewährten Zugriffsbereiche.

Token erstellen

Ein persönlicher Token wird im persönlichen Bereich im Abschnitt für persönliche Tokens erstellt. Der Tokenwert wird einmal bei der Erstellung angezeigt — speichern Sie ihn an einem sicheren Ort. Auf dem Server wird der Token nur als Hash gespeichert und kann nicht wiederhergestellt werden; bei Verlust — erstellen Sie einen neuen und löschen Sie den alten.

Alle persönlichen Tokens beginnen mit dem Präfix mbp_.

Token übermitteln

Der Token wird bei jeder Anfrage im HTTP-Header Authorization nach dem Bearer-Schema übermittelt:

Authorization: Bearer mbp_IHR_TOKEN

Derselbe Header wird auch für den Sitzungszugriff aus dem Web-Bereich verwendet (dort ist es ein kurzlebiges JWT), für Integrationen verwenden Sie jedoch den persönlichen Token mbp_….

Zugriffsbereiche (Scopes)

Ein Token hat einen Satz von Zugriffsbereichen im Format ressource:aktion. Für Lesezugriff ist das Suffix :read erforderlich, für Änderungen :write. Verfügbare Bereiche:

  • bots:read, bots:write — Bots, ihre Einstellungen, Synchronisierung, Bot-Token.
  • reactions:read, reactions:write — Reaktionen, Import, Formeltest, Verknüpfungen, Reihenfolge.
  • labels:read, labels:write — Abonnenten-Labels.
  • collections:read, collections:write — Sammlungen und Einträge.
  • flows:read, flows:write — Szenarien.
  • integrations:read, integrations:write — Integrationen, Verbindungen, Zugangsdaten.
  • media:write — Upload in die Medienbibliothek.
  • templates:read, templates:write — Bot-Vorlagen.
  • settings:read, settings:write — Einstellungen.
  • subscribers:read — Abonnenten und Dialogverlauf (Lesezugriff).
  • broadcasts:write — Broadcasts und deren Verwaltung.
  • stats:read — Statistik und Analytik.
  • billing:read — Guthaben und Tarife (Lesezugriff).

Der besondere Bereich * gewährt vollständigen Zugriff auf alle öffentlichen Endpunkte.

Was per Token zugänglich ist und was nicht

Unter einem persönlichen Token sind nur Konstruktor-Endpunkte zugänglich — jene, die „beim Bot-Aufbau helfen". Über PAT nicht zugänglich (nur aus einer Web-Sitzung): Anmeldung und Registrierung, mobile Endpunkte, Bezahlung und Guthabenaufladung, Benachrichtigungen, Audit-Journal, Operator-Nachrichtenversand in den Dialog, eingehende Webhooks und Zahlungs-Callbacks, WebSocket. Eine Anfrage mit einem mbp_-Token an eine solche Route gibt 401 oder 403 zurück.

Wenn dem Token der benötigte Bereich für eine bestimmte Route fehlt, wird 403 zurückgegeben. Mehr zu Codes im Leitfaden zu Fehlern.

Nächste Schritte

  • API-Schnellstart — erste Anfrage mit Token.
  • Fehler — Bedeutung von 401 und 403.
  • MCP — derselbe Token für die agentische Schnittstelle.