API-Zugriffstoken

Ein API-Zugriffstoken ist eine eindeutige Kennung, die einem bestimmten Projekt oder mehreren Projekten in Ihrem Konto zugewiesen ist. Er authentifiziert Ihr Konto für die Verwaltung Ihrer Projekte über die API, einschließlich Kontoänderungen, Senden von Nachrichten, Bearbeiten von Projekten usw.

Arten von API-Zugriffstoken

Pushwoosh bietet zwei verschiedene Arten von API-Zugriffstoken: Server und Device.

Jeder Tokentyp ist nur für seinen spezifischen API-Geltungsbereich gültig. Ein Authentifizierungsfehler tritt auf, wenn der falsche Token verwendet wird.

Server-API-Token

Der Server-API-Token wird mit allen API-Methoden verwendet, außer denen der Geräte-API. Er sollte im Request-Body im Feld auth enthalten sein.

Geräte-API-Token

Der Geräte-API-Token wird ausschließlich mit den Methoden der Geräte-API verwendet. Er sollte in den HTTP-Request-Headern unter Verwendung des Authorization-Headers eingefügt werden. Unten finden Sie ein Beispiel für das korrekte Header-Format:

Authorization: Token <device_api_token>

Ersetzen Sie <device_api_token> durch den tatsächlichen Wert Ihres Geräte-API-Tokens.

Methoden, die einen Geräte-API-Token erfordern

Die folgenden API-Methoden erfordern einen Geräte-API-Token zur Autorisierung:

• registerDevice
• unregisterDevice
• deleteDevice
• setTags
• getTags
• setBadge
• applicationOpen
• pushStat
• messageDeliveryEvent
• registerUser
• deleteUser
• postEvent
• registerEmail
• deleteEmail
• setEmailTags
• registerEmailUser
• getInboxMessages
• inboxStatus

API-Zugriffstoken erstellen und verwalten

Sie können Ihre API-Zugriffstoken im Bereich API-Zugriff des Pushwoosh Control Panels anzeigen, erstellen und verwalten. Um darauf zuzugreifen, gehen Sie zu Einstellungen → API-Zugriff.

Standardmäßig enthält jedes Konto einen Token namens Pushwoosh Demo App, der als Server-Token eingerichtet ist.

Einen neuen API-Zugriffstoken erstellen

So erstellen Sie einen neuen API-Zugriffstoken:

1. Gehen Sie zum Bereich API-Zugriff im Control Panel.

2. Klicken Sie auf Neuen Token generieren.

3. Wählen Sie im erscheinenden Fenster den Tokentyp aus:

   • Server wird für die meisten API-Methoden verwendet (ausgenommen Geräte-API-Methoden).

   • Gerät wird nur für Geräte-API-Methoden verwendet.

4. Geben Sie einen Namen für den Token ein.

5. Klicken Sie auf Generieren, um den Token zu erstellen.

Wichtig: Stellen Sie sicher, dass Sie dem Token Zugriff auf die richtige App in Ihrem Pushwoosh Control Panel gewähren. Mehr erfahren

Der neue Token wird in der API-Zugriffsliste angezeigt. Von dort aus können Sie seinen Wert für die Verwendung in API-Anfragen kopieren oder seine Zugriffsberechtigungen nach Bedarf verwalten.

Einen Token verwalten

Um einen bestehenden API-Token zu verwalten, klicken Sie auf das Drei-Punkte-Menü (⋮) neben dem Token-Eintrag im Bereich API-Zugriff.

Die folgenden Optionen sind verfügbar:

Zugriff auf alle Projekte gewähren

Gewährt dem Token Zugriff auf alle Projekte in Ihrem Konto. Dies ermöglicht ihm die vollständige Nutzung der API über alle Projekte hinweg.

Tipp

Geben Sie nur den Tokens vollen Zugriff, die ihn benötigen. Dies hilft, Ihre Daten sicher zu halten und den Zugriff zu kontrollieren.

Zugriff von allen Projekten entziehen

Entfernt den Zugriff des Tokens auf alle Projekte in Ihrem Konto. Der Token kann die API nicht mehr verwenden, bis der Zugriff erneut gewährt wird.

Token bearbeiten

Öffnet den Bildschirm API-Token-Berechtigungen bearbeiten, wo Sie können:

• Den Token-Namen ändern

• Den Token-Wert kopieren

• Wählen Sie aus, auf welche Projekte der Token zugreifen kann, indem Sie sie in der Liste auswählen oder abwählen

• Die Berechtigungen des Tokens ein- oder ausschalten: Kontoänderung, Anwendungsänderung, Tag-Änderung, Nachrichten senden & löschen

• Die erlaubten IP-Adressen festlegen, von denen der Token verwendet werden kann (nur Server-Token)

Der Tab Berechtigungen zeigt auch die letzte Nutzungszeit des Tokens und wie viele seiner Aufrufe in den letzten 7 und 30 Tagen abgelehnt wurden.

Nachdem Sie Ihre Änderungen vorgenommen haben, klicken Sie auf Speichern, um sie zu übernehmen.

Tipp

Geben Sie Tokens nur Zugriff auf die Projekte, die sie benötigen. Dies hilft, Ihr Konto zu schützen und zu kontrollieren, was jeder Token tun kann.

Nutzungsprotokoll eines Tokens überprüfen

Öffnen Sie den Tab Nutzungsprotokoll auf dem Bildschirm „API-Token-Berechtigungen bearbeiten“, um jeden API-Aufruf, der mit dem Token in den letzten 90 Tagen gemacht wurde, zu überprüfen. Wählen Sie ein Ergebnis (Beliebiges Ergebnis, Akzeptiert, Abgeschlossen, Abgelehnt: IP-Adresse, Abgelehnt: keine Rechte) und einen Datumsbereich aus und klicken Sie dann auf Anwenden, um die Liste zu filtern. Klicken Sie auf CSV exportieren, um das gefilterte Protokoll als CSV-Datei herunterzuladen.

Token löschen

Entfernt den Token dauerhaft aus Ihrem Konto.

Vorsicht

Diese Aktion kann nicht rückgängig gemacht werden. Einmal gelöscht, kann der Token nicht wiederhergestellt werden. Stellen Sie sicher, dass der Token nicht mehr verwendet wird, bevor Sie ihn löschen.

API-Anfragen autorisieren

Um API-Anfragen zu autorisieren, verwenden Sie den korrekten Typ des API-Zugriffstokens basierend auf dem Typ der API-Methode, die Sie aufrufen:

Für Server-API-Methoden

Fügen Sie den Token in das “auth”-Feld des Anfragekörpers ein:

Beispiel:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // Fügen Sie hier Ihren Server-Token ein
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

Für Geräte-API-Methoden

Verwenden Sie den Geräte-Token. Fügen Sie ihn in den HTTP-Request-Header im folgenden Format ein:

Authorization: Token <device_api_token>

Ersetzen Sie <device_api_token> durch Ihren tatsächlichen Token-Wert.

Vorsicht

Stellen Sie sicher, dass der Tokentyp mit der von Ihnen verwendeten API-Methode übereinstimmt. Wenn der Token nicht mit dem erforderlichen Typ übereinstimmt, gibt die Anfrage einen Authentifizierungsfehler zurück.

Einen Token auf bestimmte IP-Adressen beschränken

Ein Server-Token kann auf eine Liste erlaubter Quell-IP-Adressen beschränkt werden. Wenn die Liste festgelegt ist, akzeptiert Pushwoosh nur API-Anfragen, die mit diesem Token von einer übereinstimmenden Adresse gemacht werden. Geräte-Token haben diese Option nicht.

Öffnen Sie Token bearbeiten für einen Server-Token und geben Sie die Adressen in Erlaubte IP-Adressen ein:

• Fügen Sie bis zu 50 Einträge hinzu, IPv4 oder IPv6, jeweils eine einzelne Adresse (203.0.113.7) oder ein CIDR-Bereich (203.0.113.0/24).
• Eine einzelne Adresse wird als Bereich voller Länge gespeichert, z.B. wird 203.0.113.7 zu 203.0.113.7/32.
• Ein Bereich wird auf seine Netzwerkadresse kanonisiert, z.B. wird 203.0.113.7/24 zu 203.0.113.0/24.
• 0.0.0.0/0 und ::/0 werden abgelehnt, da sie jeder Adresse entsprechen und keine Einschränkung bieten würden.
• Lassen Sie die Liste leer, um den Token von jeder Adresse aus nutzbar zu halten. Dies ist die Standardeinstellung für bestehende und neue Token.

Klicken Sie auf Speichern, um die Liste zu übernehmen. Das Speichern wird abgelehnt, wenn die Liste mehr als 50 Einträge oder einen Eintrag enthält, der keine gültige Adresse oder kein gültiger CIDR-Bereich ist.

Was passiert, wenn eine Anfrage von einer nicht erlaubten Adresse kommt

Pushwoosh überprüft die erlaubten IP-Adressen bei jedem API-Aufruf, der mit dem Token gemacht wird, egal ob es sich um einen v1-REST-Aufruf (wie in dieser API-Referenz dokumentiert, zum Beispiel die Messages API), einen Messaging API v2-Aufruf oder einen Customer Journey API-Aufruf handelt. Eine Anfrage von einer Adresse außerhalb der erlaubten Liste des Tokens wird abgelehnt.

Das Antwortformat unterscheidet sich je nachdem, welche Aufrufe Sie tätigen:

• Das Senden, Abbrechen und Löschen von Nachrichten, wie createMessage, die kanalspezifischen create*Message-Methoden, cancelMessage und deleteMessage, geben HTTP 200 mit "status_code": 403 im Antwortkörper zurück, genauso wie bei ihren anderen Autorisierungsfehlern.
• Andere v1-REST-Aufrufe, wie die APIs für Anwendungen, Tags, Geozonen, Segmentierung (Filter), Kampagnen, Voreinstellungen, Testgeräte und Statistiken, geben einen echten HTTP 403 mit einem JSON-Fehlerkörper zurück.
• Messaging API v2 und die Customer Journey API geben HTTP 403 mit einem PermissionDenied-Fehler zurück.

Änderungen an der Zulassungsliste benötigen bis zu 10 Minuten, um überall wirksam zu werden

Pushwoosh speichert die Token-Validierung für 10 Minuten im Cache, und die Cache-Invalidierung läuft pro Rechenzentrum. Das Einschränken oder Entfernen erlaubter Adressen wird im Rechenzentrum, in dem die Änderung vorgenommen wurde, sofort wirksam und in den anderen innerhalb von 10 Minuten.