Authentifizierung und Tokens
Programmzugriff auf GetMyBot einrichten: persönlichen Token erstellen, einen Bereich wählen und nur benötigte Aktionen erlauben.
Auf dieser Seite
Ein persönlicher Token lässt ein Programm auf GetMyBot zugreifen, ohne Ihr Passwort weiterzugeben. In der Dokumentation heißt er PAT (Personal Access Token). Für die Bot-Liste genügt beispielsweise bots:read; eine neue Reaktion erfordert reactions:write.
Wählen Sie bei der Erstellung genau einen Kontobereich und die nötigen Berechtigungen, die Scopes. Der Token funktioniert nur dort und verleiht nicht mehr Rechte als Ihr eigenes Konto. Der API-Schnellstart zeigt die erste Anfrage.
Token erstellen
Erstellen Sie den persönlichen Token im entsprechenden Bereich Ihres Kontos. Der Wert wird einmal angezeigt; speichern Sie ihn sicher. Auf dem Server liegt nur sein Hash. Ein verlorener Token kann nicht wiederhergestellt werden: Erstellen Sie einen neuen und löschen Sie den alten.
Alle persönlichen Tokens beginnen mit mbp_.
Token übermitteln
Senden Sie den Token in jeder Anfrage im HTTP-Header Authorization als Bearer:
Authorization: Bearer <PERSÖNLICHER_TOKEN>
Ersetzen Sie den Platzhalter einschließlich der spitzen Klammern durch den vollständigen angezeigten Token samt mbp_. Fügen Sie das Präfix nicht erneut hinzu. Der MCP-Server akzeptiert nur persönliche Tokens; ein Projekt-API-Token (mb_live_…) ist ungeeignet.
Denselben Header verwendet das Web-Dashboard für seinen kurzlebigen Sitzungs-JWT. Für Integrationen verwenden Sie jedoch den persönlichen mbp_-Token.
Kontobereich des Tokens
Ein Token gilt für genau einen Kontobereich. Standardmäßig ist das Ihr eigener. Haben Sie Zugang zu einem fremden Kontobereich, können Sie ihn bei der Erstellung auswählen: in der API über account_id im Körper von POST /api/tokens, im Dashboard über die Auswahlliste oberhalb der Gültigkeitsdauer. GET /api/account/cabinets listet die verfügbaren Bereiche.
Praktisch bedeutet das:
GET /api/botsliefert nur Bots des gewählten Kontobereichs, weder Ihre eigenen noch die eines dritten Bereichs.- Ein Bot aus einem anderen Bereich liefert
404, genau wie ein fremder Bot. Der Token verrät nicht, ob die ID anderswo existiert. - Es gelten weiterhin Ihre Rechte. Der Token beschränkt sie auf einen Bereich, erweitert sie aber nicht. Teilnehmerrolle im Bereich und botbezogene Rechte entscheiden über mögliche Aktionen.
- Für einen fremden Bereich ausgestellte Tokens gelten mit Ihren Rechten in diesem Bereich. Abrechnungsdaten (
/api/billing/*) erfordernbilling.read, das Anlegen von Projektenbots.create. Auch der Scope*verleiht keine zusätzlichen Bereichsrechte. - Wird Ihr Bereichszugriff entzogen, funktioniert der Token ab der nächsten Anfrage nicht mehr. Gesondertes Widerrufen ist unnötig.
Zugang zu einem Bereich nur über einen Bot
GET /api/account/cabinets zeigt pro Bereich ein Feld source:
self: Ihr eigener Bereich;account: Ihnen wurde Zugang zum ganzen Bereich gegeben, die Rolle bestimmt Rechte;bot: Sie haben nur Zugang zu einem einzelnen Bot dieses Bereichs, keine Rechte am ganzen Bereich.
Bei source: "bot" funktionieren Aktionen am freigegebenen Bot im Rahmen seiner Rechte. Bereichsweite Vorgänge wie Bot-Verbindung und Abrechnung werden abgelehnt. REST liefert 403 mit {"error":"missing cabinet right"} oder, bei bestehender Mitgliedschaft ohne Einzelrecht, missing cabinet right: <Recht>. In MCP lautet der Werkzeugfehler permission denied: missing cabinet right. connect_bot braucht etwa bots.create; Abrechnungswerkzeuge brauchen billing.read oder billing.write.
Der Eigentümer kann Sie unter Zugang zum Kontobereich mit dem nötigen Recht einladen. Sie müssen den Token nicht neu ausstellen: Nach Annahme der Einladung funktioniert er ab der nächsten Anfrage.
Vor Einführung dieser Möglichkeit ausgestellte Tokens sind an Ihren eigenen Bereich gebunden. Hat ein solcher Token zuvor auf einen freigegebenen Bot aus einem fremden Bereich zugegriffen, stellen Sie für jenen Bereich einen separaten Token aus.
Scopes
Scopes haben das Format ressource:aktion. Lesen erfordert :read, Ändern :write. Verfügbar sind:
| Scope | Erlaubnis |
|---|---|
bots:read, bots:write | Bots, Einstellungen, Synchronisierung und Bot-Token |
reactions:read, reactions:write | Reaktionen, Import, Formeltest, Verknüpfungen und 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 und Zugangsdaten |
media:write | Upload in die Medienbibliothek |
templates:read, templates:write | Bot-Vorlagen |
settings:read, settings:write | Einstellungen |
subscribers:read | Abonnenten und Dialogverlauf lesen |
broadcasts:write | Broadcasts verwalten |
stats:read | Statistik und Analytik |
billing:read | Guthaben und Tarife lesen |
Der besondere Scope * erlaubt alle öffentlichen Endpoints, jedoch nur im Rahmen Ihrer übrigen Rechte.
Was per Token zugänglich ist
Persönliche Tokens gelten nur für Builder-Endpoints, also Funktionen zum Aufbau des Bots. Nur aus einer Web-Sitzung zugänglich und daher nicht per PAT sind Anmeldung, Registrierung, mobile Endpoints, Zahlung und Aufladung, Benachrichtigungen, Audit-Journal, Nachrichten von Mitarbeitern im Dialog, eingehende Webhooks, Zahlungs-Callbacks und WebSocket. Eine Anfrage mit mbp_ an solche Routen liefert 401 oder 403.
Fehlt dem Token der für eine erlaubte Route nötige Scope, liefert sie 403. Siehe API-Fehler.
Scopes für KI-Agentenfunktionen
managed_ai:invokeundmanaged_ai:usage:read: KI-Aufrufe über die gemeinsame Anbieterschnittstelle und Verbrauch lesen.copilot:use: Copilot-Vorschläge. Diagnose brauchtjourney:read; Schemaänderungen zusätzlichjourney:edit.journey:readundjourney:edit: Abläufe analysieren, Ausführungen erklären, Flow Intelligence und Explainable Replay.- Meta-Verbindungen verwenden Integrations- und Bot-Scopes; zusätzlich werden Rechte am Kontobereich und am konkreten Bot geprüft.
MCP wendet dieselben Berechtigungsprüfungen an. Eine MCP-Verbindung fügt dem Token keine Rechte an anderen Bereichen oder Bots hinzu.
Weiterführende Artikel
- API-Schnellstart: erste Anfrage.
- API-Fehler:
401und403. - MCP: derselbe Token für Agenten.