Aperçu de l’API

Cet article de référence couvre les bases de l’API, y compris la terminologie courante et un aperçu des clés de l’API REST, des autorisations et de la manière de les sécuriser.

Collection d’API REST de Braze

Définitions relatives aux API

Voici un aperçu des termes que vous pouvez rencontrer dans la documentation de l’API REST de Braze.

Endpoints

Braze gère un certain nombre d’instances différentes pour notre tableau de bord et nos endpoints REST. Une fois votre compte provisionné, vous vous connectez à l’une des URL suivantes. Utilisez le bon endpoint REST en fonction de l’instance qui vous a été attribuée. En cas de doute, ouvrez un ticket d’assistance ou utilisez le tableau suivant pour faire correspondre l’URL du tableau de bord que vous utilisez au bon endpoint REST.

Pour localiser votre endpoint REST dans Braze :

1. Connectez-vous à Braze et accédez à Settings > APIs and Identifiers > API Keys.
2. Sélectionnez une clé API existante ou choisissez Create API Key pour en générer une nouvelle.
3. Copiez l’endpoint REST affiché dans cet onglet et utilisez-le pour vos requêtes API.

Important

Lorsque vous utilisez des endpoints pour les appels API, utilisez l’endpoint REST.

Pour l’intégration SDK, utilisez l’endpoint SDK et non l’endpoint REST.

Limites de l’API

Pour la plupart des API, Braze applique une limite de débit par défaut de 250 000 requêtes par heure. Cependant, certains types de requêtes sont soumis à leur propre limite de débit afin de mieux gérer les volumes élevés de données au sein de la base client. Pour plus d’informations, consultez les limites de débit de l’API.

ID utilisateur

• ID externe : Le external_id sert d’identifiant utilisateur unique pour lequel vous soumettez des données. Cet identifiant doit être identique à celui que vous avez défini dans le SDK Braze afin d’éviter de créer plusieurs profils pour le même utilisateur.
• ID utilisateur Braze : Le braze_id sert d’identifiant utilisateur unique défini par Braze. Vous pouvez utiliser cet identifiant pour supprimer des utilisateurs via l’API REST, en plus des external_ids.

Pour plus d’informations, consultez les articles suivants en fonction de votre plateforme : iOS, Android et Web.

À propos des clés API REST

Une clé API REST (clé d’interface de programmation d’applications REST) est un code unique que vous transmettez à une API afin d’authentifier l’appel et d’identifier l’application ou l’utilisateur à l’origine de la requête. Vous accédez à l’API via des requêtes Web HTTPS vers l’endpoint de l’API REST de votre entreprise. Les clés API REST fonctionnent en tandem avec les clés d’identifiant d’application pour suivre, accéder, envoyer, exporter et analyser les données, et ainsi garantir le bon fonctionnement de l’ensemble.

Chez Braze, les espaces de travail et les clés API vont de pair. Les espaces de travail sont conçus pour héberger des versions de la même application sur plusieurs plateformes. De nombreux clients utilisent également des espaces de travail pour contenir des versions gratuites et premium de leurs applications sur la même plateforme. Comme vous pouvez le constater, ces espaces de travail utilisent également l’API REST et possèdent leurs propres clés API REST. Ces clés peuvent être configurées individuellement pour inclure l’accès à des endpoints spécifiques de l’API. Chaque appel à l’API doit inclure une clé ayant accès à l’endpoint concerné.

Nous désignons à la fois la clé API REST et la clé API de l’espace de travail sous le terme api_key. Le api_key est inclus dans chaque requête en tant qu’en-tête de requête et sert de clé d’authentification vous permettant d’utiliser nos API REST. Ces API REST sont utilisées pour suivre les utilisateurs, envoyer des messages, exporter des données utilisateur, etc. Lorsque vous créez une nouvelle clé API REST, vous devez lui accorder l’accès à des endpoints spécifiques. En affectant des autorisations spécifiques à une clé API, vous pouvez limiter précisément les appels qu’elle peut authentifier.

Conseil

En plus des clés API REST, il existe un type de clé appelé clés d’identification, qui permet de référencer des éléments spécifiques tels que des applications, des modèles, des Canvas, des Campaigns, des Content Cards et des Segments depuis l’API. Pour plus d’informations, reportez-vous aux types d’identifiants API.

Créer des clés API REST

Pour créer une nouvelle clé API REST :

1. Allez dans Settings > APIs and Identifiers.
2. Sélectionnez Create API Key.
3. Donnez un nom à votre nouvelle clé pour l’identifier d’un coup d’œil.
4. Spécifiez les adresses IP autorisées et les sous-réseaux pour cette nouvelle clé.
5. Sélectionnez les autorisations que vous souhaitez associer à votre nouvelle clé.

Important

N’oubliez pas qu’après avoir créé une nouvelle clé API, vous ne pouvez plus modifier l’étendue des autorisations ni les adresses IP autorisées. Cette restriction est en place pour des raisons de sécurité. Si vous devez modifier le périmètre d’une clé, créez-en une nouvelle avec les autorisations mises à jour et implémentez-la à la place de l’ancienne. Une fois la mise en œuvre terminée, vous pouvez supprimer l’ancienne clé.

Autorisations de clé API REST

Les autorisations de clés API sont des droits que vous pouvez affecter à un utilisateur ou un groupe pour limiter leur accès à certains appels API. Pour afficher la liste des autorisations de votre clé API, allez dans Settings > APIs and Identifiers, et sélectionnez votre clé API.

• user data
• email
• messages
• campaigns
• canvas
• segments
• purchases
• events
• sessions
• kpis
• templates
• sso
• content blocks
• preference center
• subscription
• sms
• catalogs
• sdk authentication

Gestion des clés API REST

Vous pouvez afficher les détails des clés API REST existantes ou les supprimer depuis Settings > APIs and Identifiers > onglet API Keys. Notez que vous ne pouvez pas modifier les clés API REST une fois qu’elles ont été créées.

L’onglet API Keys contient les informations suivantes pour chaque clé :

Pour afficher les détails d’une clé API, survolez la clé et sélectionnez View. Vous y trouverez toutes les autorisations dont dispose cette clé, les adresses IP inscrites sur la liste d’autorisations (le cas échéant) et si cette clé est inscrite sur la liste d’autorisations d’adresses IP de Braze.

Notez que lorsque vous supprimez un utilisateur, Braze ne supprime pas les clés API associées créées par cet utilisateur. Pour supprimer une clé, survolez-la et sélectionnez Delete.

Sécurité des clés API REST

Les clés API servent à authentifier les appels API. Quand vous créez une nouvelle clé API REST, vous devez lui accorder l’accès à des endpoints spécifiques. En affectant des autorisations spécifiques à une clé API, vous pouvez limiter précisément les appels qu’elle peut authentifier.

Étant donné que les clés API REST permettent d’accéder à des endpoints API REST potentiellement sensibles, sécurisez ces clés et partagez-les uniquement avec des partenaires de confiance. Elles ne doivent jamais être exposées publiquement. Par exemple, n’utilisez pas cette clé pour effectuer des appels AJAX depuis votre site Web et ne l’exposez d’aucune autre manière publique.

Une bonne pratique de sécurité consiste à n’accorder à un utilisateur que les accès nécessaires à l’accomplissement de son travail. Ce principe s’applique également aux clés API en affectant des autorisations à chaque clé. Ces autorisations vous offrent une meilleure sécurité et un meilleur contrôle sur les différentes parties de votre compte.

Avertissement

Étant donné que les clés API REST permettent d’accéder à des endpoints API REST potentiellement sensibles, assurez-vous qu’elles sont stockées et utilisées en toute sécurité. Par exemple, n’utilisez pas cette clé pour effectuer des appels AJAX depuis votre site Web et ne l’exposez d’aucune autre manière publique.

Si vous divulguez accidentellement une clé, vous pouvez la supprimer depuis la console de développement. Pour obtenir de l’aide, ouvrez un ticket d’assistance.

Sécurité des clés API REST et des clés API SDK

Les clés API REST et les clés API SDK présentent des profils de sécurité différents.

Liste d’adresses IP autorisées

Pour renforcer la sécurité, vous pouvez établir une liste des adresses IP et sous-réseaux exclusivement autorisés à envoyer des requêtes API REST pour une clé API REST donnée. C’est ce qu’on appelle la liste d’autorisations (ou liste blanche). Pour autoriser des adresses IP ou des sous-réseaux spécifiques, indiquez-les dans la section Whitelist IPs lors de la création d’une nouvelle clé API REST :

Si vous n’en spécifiez aucune, les requêtes pourront être envoyées depuis n’importe quelle adresse IP.

Conseil

Si vous créez un webhook Braze à Braze et utilisez une liste d’autorisations, consultez la liste des adresses IP à ajouter à la liste blanche.

Authentification et sécurité de l’API

Authentification par jeton Bearer

Braze authentifie les requêtes API REST à l’aide de la clé API REST transmise sous forme de jeton Bearer dans l’en-tête Authorization de la requête. Lorsque vous envoyez une requête, incluez votre clé API dans le format suivant :

1
Authorization: Bearer YOUR_REST_API_KEY

À chaque requête, Braze effectue les vérifications suivantes côté serveur :

1. Validité du jeton : Vérifie que la clé API REST existe dans Braze et qu’elle est active (c’est-à-dire qu’elle n’a pas été révoquée ou désactivée).
2. Autorisation du jeton : Confirme que la clé API dispose des autorisations requises pour l’endpoint demandé.

Si l’authentification échoue, l’API renvoie une réponse d’erreur avec un code d’état HTTP. Par exemple, 401 Unauthorized indique une clé non valide ou manquante, tandis que 403 Forbidden indique que la clé ne dispose pas des autorisations nécessaires pour l’endpoint demandé. Pour plus d’informations, consultez la section Erreurs API.

Sécurité au niveau du réseau

Les requêtes API REST adressées à Braze sont protégées par le chiffrement TLS (sécurité de la couche de transport) sur l’ensemble du chemin de la requête. Le tableau suivant décrit le flux réseau d’une requête API de votre serveur vers Braze :

Le chiffrement TLS couvre chaque maillon de la chaîne. Votre serveur se connecte à Cloudflare via TLS, et Cloudflare établit une connexion TLS distincte via le NLB vers l’ingress NGINX, de sorte que votre clé API et vos données de requête restent chiffrées pendant le transit.

Ressources complémentaires

Bibliothèque client Ruby

Si vous implémentez Braze avec Ruby, vous pouvez utiliser la bibliothèque client Ruby pour réduire le temps d’importation de vos données. Une bibliothèque client est une collection de code spécifique à un langage de programmation — ici Ruby — qui facilite l’utilisation d’une API.

La bibliothèque client Ruby prend en charge les endpoints utilisateur.

Important

Cette bibliothèque client est en version bêta. Pour contribuer à son amélioration, envoyez vos commentaires à [email protected].