API-Tokens

Was ist ein API-Token

Ein API-Token (APPLICATION_TOKEN) ist der geheime Schlüssel, mit dem sich Ihre Anwendung gegenüber der BulkGate API authentifiziert. Zusammen mit der Application ID (APPLICATION_ID) bildet er den vollständigen Satz an Zugangsdaten — ohne beide lehnt die API die Anfrage ab.

Der Token ist eine zufällige Zeichenfolge aus 50 Zeichen, bestehend aus Ziffern sowie Klein- und Großbuchstaben. Er wird verschlüsselt gespeichert und läuft nicht ab — er bleibt gültig, bis Sie ihn selbst neu generieren, deaktivieren oder löschen.

Ein Token wird automatisch in dem Moment erstellt, in dem Sie die API anlegen. Weitere können Sie jederzeit hinzufügen — zum Beispiel einen pro Server oder pro Umgebung, damit sich ein einzelner Token widerrufen lässt, ohne die anderen zu beeinträchtigen.

Wo Sie den Token finden

1. Klicken Sie im Menü des Portals auf Module und APIs
2. Klicken Sie unter Meine APIs und Module auf die Karte Ihrer Anwendung
3. Bleiben Sie auf der Registerkarte Die Einstellungen und suchen Sie den Abschnitt Anmeldedaten

Er enthält die Application ID und darunter, unter der Zwischenüberschrift Application Token, die Liste der Tokens dieser Anwendung. Ein Token wird nie sofort angezeigt — Sie sehen nur seine ersten und letzten vier Zeichen, der Rest ist durch Sternchen ersetzt.

Das Symbol links zeigt den Zustand des Tokens: Grün bedeutet aktiviert, Rot deaktiviert. Ein deaktivierter Token ist zusätzlich durchgestrichen.

Die Schaltfläche mit dem durchgestrichenen Auge rechts neben jedem Token zeigt ihn an; die übrigen Aktionen verbergen sich hinter dem Drei-Punkte-Symbol Mehr Aktionen.

Token anzeigen und kopieren

1. Klicken Sie auf das durchgestrichene Auge neben dem Token, den Sie sehen möchten
2. Es öffnet sich der Dialog Token anzeigen, der Sie bittet, Ihre Umgebung zu prüfen
3. Geben Sie das Passwort Ihres Kontos ein und klicken Sie auf Fortsetzen
4. Der Token wird vollständig ausgeschrieben und das Symbol ändert sich zu Kopieren, womit er in die Zwischenablage kopiert wird

Weiteren Token hinzufügen

1. Klicken Sie unten im Abschnitt Anmeldedaten auf Token hinzufügen
2. Geben Sie das Passwort Ihres Kontos ein
3. Klicken Sie auf Hinzufügen

Das Portal bestätigt mit Token wurde erstellt und schreibt den neuen Token vollständig aus — kopieren Sie ihn sofort, denn nach dem Neuladen wird er wie die anderen maskiert. Die Anzahl der Tokens pro Anwendung ist nicht begrenzt.

Token neu generieren

Beim Neugenerieren wird der bestehende Token durch einen neuen überschrieben. Er behält seinen Platz in der Liste, nur sein Wert ändert sich.

1. Klicken Sie neben dem Token auf Mehr Aktionen und wählen Sie Erzeugen Sie ein neues
2. Geben Sie das Passwort Ihres Kontos ein
3. Klicken Sie auf Erzeugen Sie ein neues

Das Portal bestätigt mit Token wurde regeneriert.

Token deaktivieren und wieder aktivieren

Das Deaktivieren eines Tokens ist die umkehrbare Alternative zum Löschen: Der Token bleibt in der Liste, kann aber nicht mehr zur Authentifizierung verwendet werden.

1. Klicken Sie neben dem Token auf Mehr Aktionen
2. Wählen Sie Deaktivieren bzw. Aktivieren bei einem bereits deaktivierten Token
3. Bestätigen Sie im sich öffnenden Dialog

Das Portal bestätigt mit Token wurde deaktiviert bzw. Token wurde aktiviert. Für diese Aktion ist kein Passwort erforderlich.

Token löschen

1. Klicken Sie neben dem Token auf Mehr Aktionen und wählen Sie Löschen
2. Bestätigen Sie im Dialog Token löschen mit Löschen

Das Portal bestätigt mit Token wurde entfernt. Auch für diese Aktion ist kein Passwort erforderlich.

Alle Tokens einer Anwendung verschwinden außerdem in dem Moment, in dem Sie die Anwendung selbst löschen.

Wie der Token an die API übergeben wird

Die Application ID und den Token übergeben Sie als Parameter application_id und application_token — entweder im Body der Anfrage oder im Query-String. Die andere Möglichkeit ist, mit dem Token ein JWT zu signieren und dieses in einem Header zu senden.

Ein ungültiger, deaktivierter oder gelöschter Token führt zu einer Antwort mit dem HTTP-Code 401 und dem Fehlertyp unknown_identity. Dieselbe Antwort erhalten Sie, wenn die Anwendung selbst deaktiviert ist oder wenn für sie erlaubte IP-Adressen eingestellt sind und die Anfrage von einer anderen Adresse kommt. Die übrigen Fehler finden Sie auf der Seite API-Fehlertypen.

Token in einem signierten JWT verwenden

Statt den Token mit jeder Anfrage zu senden, können Sie mit ihm ein JWT signieren und stattdessen dieses senden. Der Token bleibt dann auf Ihrer Seite — über das Netzwerk wird nur die daraus abgeleitete Signatur übertragen.

Das fertige JWT setzen Sie in den Header Authorization:

Damit die API es akzeptiert, muss das JWT so aussehen:

Die Payload für die Anwendung Nummer 39238 sieht also so aus:

Die Gültigkeitsdauer eines einzelnen JWT können Sie mit dem Feld expire innerhalb von application_parameters begrenzen. Der Wert ist ein Unix-Zeitstempel in Sekunden; ist er erreicht, funktioniert das JWT nicht mehr:

Ohne dieses Feld ist das JWT so lange gültig wie der Token, der es signiert hat. Das Feld ist daher überall dort nützlich, wo Sie das JWT weitergeben — Sie signieren es mit kurzer Gültigkeit und der Token selbst bleibt bei Ihnen.

Die Signatur wird gegen jeden aktivierten Token der Anwendung geprüft, Sie können das JWT also mit jedem von ihnen signieren. Ein deaktivierter oder gelöschter Token kommt nicht durch — es gilt dasselbe wie oben beschrieben: eine Antwort mit dem HTTP-Code 401 und dem Fehlertyp unknown_identity.