Anmeldung
Jeder Aufruf braucht einen Schlüssel im Header:
curl "https://api.smartchat.marketing/v1/me" -H "Authorization: Bearer $SMARTCHAT_API_KEY"Ohne Schlüssel antwortet die API mit 401 und dem Code authentication_required.
#Zwei Arten von Zugangsdaten
| API-Schlüssel | OAuth-Zugriffstoken | |
|---|---|---|
| Beginnt mit | sc_ | sc_at_ |
| Gemacht für | Deine eigene Software, Zapier, Make, n8n | AI-Assistenten, die sich mit dem MCP-Server verbinden |
| Angelegt | In der SmartChat App | Vom Assistenten, nachdem du auf einer Zustimmungsseite zugestimmt hast |
| Genutzt bei | Der REST-API und dem MCP-Server | Hauptsächlich dem MCP-Server |
Beide gehören in denselben Header. Das Feld environment in der Antwort von GET /me ist live. Eine getrennte Testumgebung (eine Sandbox) kann später folgen; das Feld ist schon da.
#Schlüssel gehören zum Konto
- Ein Schlüssel gehört zum Konto, nicht zu der Person, die ihn angelegt hat.
- Nur Personen mit der passenden Rolle legen Schlüssel an, ändern oder widerrufen sie, und nur in der App. Ein Schlüssel kann nie Schlüssel anlegen oder verwalten.
- Ein widerrufener Schlüssel funktioniert sofort nicht mehr (
api_key_revoked). Ein abgelaufener Schlüssel antwortet mitapi_key_expired. - Ein Schlüssel kann auf einige IP-Adressen begrenzt werden. Von einer anderen Adresse lautet die Antwort
ip_not_allowed. - Halte Schlüssel geheim. Wenn ein Schlüssel bekannt wird, widerrufe ihn in der App und lege einen neuen an.
#Rechte
Du wählst beim Anlegen eines Schlüssels eine Stufe. Du kannst auch einzelne Rechte anhaken.
| Level | What it means | Permissions |
|---|---|---|
| Read | Read everything that is not secret. Changes nothing, with one exception: it can request a contact export, which creates a file with personal data. | 17 |
| Draft | Everything in Read, plus create and change drafts. Nothing reaches other people. | 25 |
| All | Everything except deleting and the plan. It includes the permissions with their own checkbox; in the app you can untick them. | 38 |
Einige Rechte haben ein eigenes Kästchen, weil sie andere Menschen erreichen oder Geheimnisse zeigen: newsletters:send, templates:submit, hooks:read_secret, landing:publish und connections:run. Die Stufe All enthält sie, aber in der App hat jedes von ihnen ein eigenes Kästchen, das du abhaken kannst. Die Stufen Read und Draft enthalten sie nie.
Die Stufe Read ändert nichts, mit einer Ausnahme: Sie kann einen Kontakt-Export anfordern (eine Datei mit Namen, Telefonnummern und E-Mail-Adressen deiner Kontakte). Read schließt daher den Export personenbezogener Kontaktdaten ein. Denke daran, wenn du einen Schlüssel weitergibst. Die ganze Liste, mit den Aufrufen, die jedes Recht brauchen, steht auf der Rechte-Seite.
Fehlt einem Schlüssel ein Recht, lautet die Antwort 403 insufficient_scope und nennt das fehlende Recht in required_scope.
#Was Schlüssel nie können
Manches geht nur in der App. Ein Schlüssel oder ein Assistent kann nicht:
- Daten löschen. Erlaubt sind nur: einen Tag von einem Kontakt entfernen und einen Webhook-Endpunkt abmelden;
- den Tarif ändern, bezahlen oder das Konto verwalten (Personen einladen oder entfernen, Rollen ändern, das Konto löschen, alles exportieren);
- API-Schlüssel anlegen oder ändern, die WhatsApp-Nummer verbinden oder trennen, Rechtstexte oder Tracking ändern;
- einen Kontakt auf "confirmed" setzen. Nur der Kontakt kann bestätigen.
Ein Aufruf, der das versucht, scheitert mit action_not_allowed.