## 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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) `(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](#weiteren-token-hinzufuegen) — zum Beispiel einen pro Server oder pro Umgebung, damit sich ein einzelner Token widerrufen lässt, ohne die anderen zu beeinträchtigen. > [!CAUTION] > Geben Sie den Token niemals weiter und committen Sie ihn nie in ein öffentliches Repository. > Wer den Token und die Application ID besitzt, kann Nachrichten von Ihrem Konto senden. > Wenn Sie vermuten, dass er nach außen gelangt ist, [generieren Sie den Token neu](#token-neu-generieren) > oder [löschen Sie ihn](#token-loeschen). ## 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`. ![Der Bereich Anmeldedaten mit der Liste der Tokens](docs:api-tokens/token-list_en) ## 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 ![Der Dialog Token anzeigen mit der Abfrage des Passworts](docs:api-tokens/token-show_en) > [!NOTE] > Ein angezeigter Token bleibt nur bis zum Neuladen der Seite sichtbar. Nach dem Neuladen > ist er wieder maskiert und Sie müssen Ihr Passwort erneut eingeben, um ihn zu sehen. ## 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 Menü Mehr Aktionen mit Neu generieren, Deaktivieren und Löschen](docs:api-tokens/token-menu_en) Das Portal bestätigt mit `Token wurde regeneriert`. > [!WARNING] > Der alte Token funktioniert sofort nicht mehr. Jede Integration, die ihn verwendet > hat, erhält ab dann Fehler — setzen Sie den neuen Token unverzüglich ein. ## 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. > [!CAUTION] > Das Löschen ist endgültig — der Token lässt sich weder wiederherstellen noch erneut > anzeigen. Wenn Sie den Zugriff nur vorübergehend sperren möchten, verwenden Sie > stattdessen das [Deaktivieren des Tokens](#token-deaktivieren-und-wieder-aktivieren). 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](#token-in-einem-signierten-jwt-verwenden) 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](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/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`: ```http POST /api/1.0/simple/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json Authorization: Bearer ``` Damit die API es akzeptiert, muss das JWT so aussehen: | Teil | Inhalt | |:--|:--| | Header | `{"alg":"HS256","typ":"JWT"}` — die API akzeptiert keinen anderen Algorithmus und keinen anderen Typ | | Payload | `application_id` mit Ihrer [Application ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) | | Signatur | HMAC-SHA256 aus Header und Payload, mit dem API-Token als Schlüssel | Die Payload für die Anwendung Nummer 39238 sieht also so aus: ```json { "application_id": 39238 } ``` > [!NOTE] > Wenn Sie ein JWT senden, benötigen Sie `application_id` und `application_token` > nicht mehr unter den Parametern der Anfrage — die API entnimmt die Identität der Payload. 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: ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` 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`.