Jeton d'accès API

Un jeton d’accès API est un identifiant unique attribué à un ou plusieurs projets de votre compte. Il authentifie votre compte pour la gestion de vos projets via l’API, y compris les modifications de compte, l’envoi de messages, la modification de projets, etc.

Types de jetons d’accès API

Pushwoosh propose deux types de jetons d’accès API différents : Serveur (Server) et Appareil (Device).

Chaque type de jeton n’est valide que pour sa portée API spécifique. Une erreur d’authentification se produira si le mauvais jeton est utilisé.

Jeton API Serveur

Le jeton API Serveur est utilisé avec toutes les méthodes API, à l’exception de celles de l’API Appareil. Il doit être inclus dans le corps de la requête dans le champ auth.

Jeton API Appareil

Le jeton API Appareil est utilisé exclusivement avec les méthodes de l’API Appareil. Il doit être inclus dans les en-têtes de la requête HTTP en utilisant l’en-tête Authorization. Voici un exemple du format d’en-tête correct :

Authorization: Token <device_api_token>

Remplacez <device_api_token> par la valeur réelle de votre jeton d’accès API Appareil.

Méthodes nécessitant un jeton d'accès API Appareil

Les méthodes API suivantes nécessitent un jeton d’accès API Appareil pour l’autorisation :

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

Créer et gérer les jetons d’accès API

Vous pouvez afficher, créer et gérer vos jetons d’accès API dans la section API Access du Panneau de Contrôle Pushwoosh. Pour y accéder, allez dans Paramètres → API Access.

Par défaut, chaque compte inclut un jeton appelé Pushwoosh Demo App, qui est configuré comme un jeton serveur.

Créer un nouveau jeton d’accès API

Pour créer un nouveau jeton d’accès API :

1. Allez dans la section API Access du Panneau de Contrôle.

2. Cliquez sur Generate New Token.

3. Dans la fenêtre qui apparaît, choisissez le type de jeton :

   • Serveur utilisé pour la plupart des méthodes API (à l’exclusion des méthodes de l’API Appareil).

   • Appareil utilisé uniquement pour les méthodes de l’API Appareil.

4. Saisissez un nom pour le jeton.

5. Cliquez sur Generate pour créer le jeton.

Important : Assurez-vous de donner au jeton l’accès à la bonne application dans votre Panneau de Contrôle Pushwoosh. En savoir plus

Le nouveau jeton apparaîtra dans la liste d’accès API. À partir de là, vous pouvez copier sa valeur pour l’utiliser dans les requêtes API ou gérer ses autorisations d’accès selon vos besoins.

Gérer un jeton

Pour gérer un jeton API existant, cliquez sur le menu à trois points (⋮) à côté de l’entrée du jeton dans la section API Access.

Les options suivantes sont disponibles :

Accorder l’accès à tous les projets

Donne au jeton l’accès à tous les projets de votre compte. Cela lui permet d’utiliser pleinement l’API sur tous les projets.

Conseil

N’accordez un accès complet qu’aux jetons qui en ont besoin. Cela aide à sécuriser vos données et à contrôler les accès.

Révoquer l’accès à tous les projets

Supprime l’accès du jeton à tous les projets de votre compte. Le jeton ne pourra plus utiliser l’API jusqu’à ce que l’accès soit de nouveau accordé.

Modifier le jeton

Ouvre l’écran Edit API Token Permissions, où vous pouvez :

• Changer le nom du jeton

• Copier la valeur du jeton

• Choisir les projets auxquels le jeton peut accéder en les sélectionnant ou désélectionnant dans la liste

• Activer ou désactiver les autorisations du jeton : Modification du compte, Modification des applications, Modification des Tags, Envoi et suppression de messages

• Définir les adresses IP autorisées à partir desquelles le jeton peut être utilisé (jetons Serveur uniquement)

L’onglet Permissions affiche également la dernière heure d’utilisation du jeton et le nombre de ses appels qui ont été refusés au cours des 7 et 30 derniers jours.

Une fois que vous avez terminé vos modifications, cliquez sur Save pour les appliquer.

Conseil

N’accordez aux jetons que l’accès aux projets dont ils ont besoin. Cela aide à protéger votre compte et à contrôler ce que chaque jeton peut faire.

Consulter le journal d’utilisation d’un jeton

Ouvrez l’onglet Usage journal sur l’écran Edit API Token Permissions pour examiner chaque appel API effectué avec le jeton au cours des 90 derniers jours. Choisissez un résultat (Any outcome, Accepted, Completed, Refused: IP address, Refused: no rights) et une plage de dates, puis cliquez sur Apply pour filtrer la liste. Cliquez sur Export CSV pour télécharger le journal filtré sous forme de fichier CSV.

Supprimer le jeton

Supprime définitivement le jeton de votre compte.

Attention

Cette action est irréversible. Une fois supprimé, le jeton ne peut pas être récupéré. Assurez-vous que le jeton n’est plus utilisé avant de le supprimer.

Autoriser les requêtes API

Pour autoriser les requêtes API, utilisez le type correct de jeton d’accès API en fonction du type de méthode API que vous appelez :

Pour les méthodes de l’API Serveur

Incluez le jeton dans le champ “auth” du corps de la requête :

Exemple :

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // collez votre jeton serveur ici
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

Pour les méthodes de l’API Appareil

Utilisez le jeton Appareil. Incluez-le dans l’en-tête de la requête HTTP en utilisant le format suivant :

Authorization: Token <device_api_token>

Remplacez <device_api_token> par la valeur réelle de votre jeton.

Attention

Assurez-vous que le type de jeton correspond à la méthode API que vous utilisez. Si le jeton ne correspond pas au type requis, la requête renverra une erreur d’authentification.

Restreindre un jeton à des adresses IP spécifiques

Un jeton Serveur peut être restreint à une liste d’adresses IP sources autorisées. Lorsque la liste est définie, Pushwoosh n’accepte les requêtes API faites avec ce jeton que si elles proviennent d’une adresse correspondante. Les jetons Appareil n’ont pas cette option.

Ouvrez Modifier le jeton pour un jeton Serveur et saisissez les adresses dans Allowed IP addresses :

• Ajoutez jusqu’à 50 entrées, IPv4 ou IPv6, chacune étant une adresse unique (203.0.113.7) ou une plage CIDR (203.0.113.0/24).
• Une adresse unique est stockée comme une plage de longueur complète, par ex. 203.0.113.7 devient 203.0.113.7/32.
• Une plage est canonisée à son adresse réseau, par ex. 203.0.113.7/24 devient 203.0.113.0/24.
• 0.0.0.0/0 et ::/0 sont rejetés, car ils correspondraient à toutes les adresses et ne fourniraient aucune restriction.
• Laissez la liste vide pour que le jeton reste utilisable depuis n’importe quelle adresse. C’est le comportement par défaut pour les jetons existants et les nouveaux.

Cliquez sur Save pour appliquer la liste. L’enregistrement est rejeté si la liste contient plus de 50 entrées ou une entrée qui n’est pas une adresse ou une plage CIDR valide.

Que se passe-t-il lorsqu’une requête provient d’une adresse non autorisée

Pushwoosh vérifie les adresses IP autorisées à chaque appel API effectué avec le jeton, qu’il s’agisse d’un appel REST v1 (comme documenté dans cette référence API, par exemple l’API Messages), d’un appel à l’API de Messagerie v2 ou d’un appel à l’API Customer Journey. Une requête provenant d’une adresse en dehors de la liste autorisée du jeton est rejetée.

Le format de la réponse diffère selon les appels que vous effectuez :

• L’envoi, l’annulation et la suppression de messages, tels que createMessage, les méthodes create*Message spécifiques au canal, cancelMessage et deleteMessage, renvoient un code HTTP 200 avec "status_code": 403 dans le corps de la réponse, de la même manière que leurs autres échecs d’autorisation.
• Les autres appels REST v1, tels que les API Applications, Tags, Geozones, Segmentation (Filtres), Campagnes, Préréglages, Appareils de test et Statistiques, renvoient un véritable code HTTP 403 avec un corps d’erreur JSON.
• L’API de Messagerie v2 et l’API Customer Journey renvoient un code HTTP 403 avec une erreur PermissionDenied.

Les modifications de la liste d'autorisation peuvent prendre jusqu'à 10 minutes pour s'appliquer partout

Pushwoosh met en cache la validation des jetons pendant 10 minutes, et l’invalidation du cache s’exécute par centre de données. La restriction ou la suppression d’adresses autorisées prend effet immédiatement dans le centre de données où la modification a été effectuée, et dans les 10 minutes dans les autres.