Authentifizierung
Jede Anfrage braucht den Kopf Authorization: Bearer <token>. Andere Wege (Token in der Adresse, im Inhalt oder als Cookie) werden abgelehnt — ein Token in der Adresse sogar ausdrücklich mit token_in_url_forbidden, weil Adressen in Protokollen landen. Ein anderes Schema als Bearer (etwa Basic) beantwortet die API mit 401 invalid_authorization_scheme; fehlt der Kopf ganz, mit 401 missing_token.
Aufbau eines Tokens
m2h_live_Ab12Cd34Ef56_Zt3q…(43 Zeichen)| Teil | Bedeutung |
|---|---|
m2h | fester Präfix (erleichtert das Erkennen versehentlich veröffentlichter Tokens) |
live | Umgebung: live (Produktion), stg (Staging) oder dev (Entwicklung). Ein Token gilt nur in seiner Umgebung, sonst antwortet die API mit wrong_environment. Ausnahme: test steht für ein Sandbox-Token (siehe Sandbox), das in jeder Umgebung gilt und nur Musterdaten sieht |
Ab12Cd34Ef56 | öffentliche Kennung — erscheint in der Verwaltung und in Protokollen |
| letzter Teil | das eigentliche Geheimnis; wird bei uns nicht gespeichert, nur ein nicht umkehrbarer Fingerabdruck |
Laufzeit, Ablauf und Widerruf
Tokens gelten höchstens 365 Tage (Vorgabe 90). Nach Ablauf antwortet die API mit token_expired — legen Sie rechtzeitig ein neues Token an und tauschen Sie es im Programm aus. Ein Token lässt sich jederzeit unter Administration → API-Zugänge widerrufen; der Widerruf wirkt sofort.
Abrufprotokoll
Jeder Abruf mit einem Token wird 90 Tage protokolliert — Zeitpunkt, Methode, Pfad, Status, Fehlercode, Dauer und IP-Adresse, nie das Token selbst und nie Inhalte von Anfrage oder Antwort. Auch abgelehnte Anmeldungen mit einer bekannten Token-Kennung (falsches Geheimnis, widerrufen, abgelaufen) erscheinen dort. Verwalter sehen das Protokoll je Token unter Administration → API-Zugänge → Verlauf.
Ein Token darf nie mehr als sein Ersteller
Bei jedem Aufruf prüfen wir zusätzlich die aktuellen Rechte der Person, die das Token angelegt hat. Verliert sie ein Recht oder wird ihr Konto deaktiviert, funktioniert das Token sofort nicht mehr (insufficient_permissions bzw. invalid_token). Legen Sie Tokens für dauerhafte Anbindungen deshalb mit einem Konto an, das dauerhaft besteht.