Authentifizierung

Jeder Aufruf der Developer-API trägt ein Token im Header Authorization. Das Token bestimmt, wer handelt und welche Rechte gelten.

Sende das Token als Bearer-Token. Es gehört nie in die URL und nie in den Quellcode.

Header Authorization

Authorization: Bearer $ZENIT_TOKEN

Token-Arten und Präfixe

Ein Zugriffstoken ist dein persönliches Token für Skripte und eigene Werkzeuge und handelt als du. Ein Token besteht aus dem Präfix, 32 zufälligen Zeichen und 6 Prüfzeichen, zusammen 42 Zeichen. Zenit speichert nur einen Hash. Ein verlorenes Token lässt sich nicht wiederherstellen: Widerrufe es und lege ein neues an.

Art	Präfix	Ablauf	Angelegt	Handelt als
Zugriffstoken	zhp_	Pflicht: Standard 90 Tage, höchstens 365 Tage	im Profil, Reiter „Zugriffstokens“	du
Bot-Token	zhb_	kein Ablauf, per Erneuerung ersetzbar	beim Bot unter „Entwickler“	der Bot, begrenzt durch seine Installation

Ablauf

Ein Zugriffstoken läuft immer ab. Der Ablauf ist Pflicht.
Der Standard sind 90 Tage, höchstens sind 365 Tage möglich.
Du kannst höchstens 50 aktive Tokens haben. Beim 51. antwortet die Verwaltung mit 409 DEVELOPER_TOKEN_LIMIT_REACHED.
Ein Bot-Token läuft nicht ab. Du erneuerst es bei Bedarf, siehe Bots und Manifest.

IP-Bindung und Serverbindung

IP-Bindung

Beim Anlegen kannst du bis zu 10 IP-Bereiche in CIDR-Schreibweise eintragen, zum Beispiel 203.0.113.0/24. Das Token gilt dann nur für Aufrufe von diesen Adressen. Ein Aufruf von einer anderen Adresse bekommt 401 TOKEN_INVALID.

Serverbindung

Ohne Auswahl gilt ein Token für alle Server, auf die du Zugriff hast. Mit Serverbindung gilt es nur für die gewählten Server. Ob ein Token gebunden ist, zeigt GET /me im Feld token.serverRestricted.

Widerruf

Widerrufe ein Token im Reiter „Zugriffstokens“ deines Profils, sobald du es nicht mehr brauchst oder es in falsche Hände geraten sein könnte. Danach lehnt die API es mit 401 TOKEN_INVALID ab. Die Liste zeigt außerdem, wann und von welcher IP-Adresse ein Token zuletzt benutzt wurde. Der Zeitpunkt wird höchstens alle 10 Minuten aktualisiert.

Ein Token kann nie mehr als du

Die API prüft bei jedem Aufruf, was das Token darf und was der handelnde User gerade darf. Wirksam ist nur die Schnittmenge. Verlierst du die Freigabe für einen Server, verliert auch dein Token den Zugriff darauf, ohne dass du etwas ändern musst. Welches Recht welchen Aufruf erlaubt, steht unter Rechte.

Antwort 401 TOKEN_INVALID

Die Antwort trägt den Header WWW-Authenticate: Bearer error="invalid_token". Sie kommt, wenn das Token fehlt, falsch, abgelaufen oder widerrufen ist, das Konto gesperrt ist oder die IP-Adresse nicht erlaubt ist. Die API unterscheidet diese Fälle absichtlich nicht. Prüfe die Umgebungsvariable und das Token in deinem Profil und lege bei Bedarf ein neues an.

Beispiel: Antwort 401 TOKEN_INVALID

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
X-Request-Id: 3f2a9c1e5b7d4e08a6c2d9b41f0e7a35

{
  "code": "TOKEN_INVALID",
  "message": "Das Token fehlt, ist falsch, abgelaufen oder widerrufen.",
  "requestId": "3f2a9c1e5b7d4e08a6c2d9b41f0e7a35"
}