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 REST API de Braze

Définitions de l’API

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

Endpoints

Braze gère un certain nombre d’instances différentes pour notre tableau de bord et nos endpoints REST. Lorsque votre compte est provisionné, vous vous connectez à l’une des URL suivantes. Utilisez le bon endpoint REST en fonction de l’instance à laquelle vous êtes provisionné. 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 trouver votre endpoint REST dans Braze :

1. Connectez-vous à Braze et accédez à Paramètres > API et identifiants > Clés API.
2. Sélectionnez une clé API existante ou sélectionnez Créer une clé API pour en créer une nouvelle.
3. Copiez l’endpoint REST affiché dans cet onglet et utilisez cet endpoint pour vos requêtes API.

Important

Lorsque vous utilisez des endpoints pour des 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 limitation du débit par défaut de 250 000 requêtes par heure. Cependant, certains types de requêtes ont leur propre limite de débit pour mieux gérer les volumes élevés de données à travers la base de clients. Pour plus de détails, consultez Limites de débit de l’API

ID utilisateur

• ID externe de l’utilisateur : Le external_id sert d’identifiant utilisateur unique pour lequel vous soumettez des données. Cet identifiant doit être le même que celui que vous avez défini dans le SDK de 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 la REST API 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 REST API

Une clé REST API (REST Application Programming Interface) est un code unique que vous transmettez à une API pour authentifier l’appel API et identifier l’application ou l’utilisateur appelant. Vous accédez à l’API en effectuant des requêtes web HTTPS vers l’endpoint REST API de votre entreprise. Les clés REST API fonctionnent en tandem avec les clés d’identifiant d’application pour suivre, accéder, envoyer, exporter et analyser les données, afin de garantir que tout fonctionne correctement.

Les espaces de travail et les clés API vont de pair chez Braze. Les espaces de travail sont conçus pour héberger les versions d’une même application sur plusieurs plateformes. De nombreux clients utilisent également les espaces de travail pour contenir les versions gratuites et premium de leurs applications sur la même plateforme. Comme vous l’avez peut-être remarqué, ces espaces de travail utilisent également la REST API et possèdent leurs propres clés REST API. 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 ciblé.

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

Conseil

En plus des clés REST API, il existe également un type de clé appelé clés d’identifiant qui peut être utilisé pour 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, consultez les types d’identifiants API.

Créer des clés REST API

Pour créer une nouvelle clé REST API :

1. Allez dans Paramètres > API et identifiants.
2. Sélectionnez Créer une clé API.
3. Donnez un nom à votre nouvelle clé pour l’identifier facilement en un coup d’œil.
4. Spécifiez les adresses IP autorisées et les sous-réseaux pour la nouvelle clé.
5. Sélectionnez les permissions que vous souhaitez associer à votre nouvelle clé.

Important

Gardez à l’esprit qu’après avoir créé une nouvelle clé API, vous ne pouvez pas modifier la portée des permissions ni les adresses IP autorisées. Cette limitation est en place pour des raisons de sécurité. Si vous devez modifier la portée d’une clé, créez une nouvelle clé avec les permissions mises à jour et implémentez cette clé à la place de l’ancienne. Une fois votre implémentation terminée, vous pouvez supprimer l’ancienne clé.

Permissions des clés REST API

Les permissions des clés API sont des autorisations que vous pouvez attribuer à un utilisateur ou un groupe pour limiter leur accès à certains appels API. Pour afficher votre liste de permissions de clés API, allez dans Paramètres > API et identifiants, puis sélectionnez votre clé API.

• données utilisateur
• e-mail
• messages
• campaigns
• canvas
• segments
• achats
• événements
• sessions
• kpi
• modèles
• authentification unique
• content blocks
• centre de préférences
• abonnement
• sms
• catalogues
• authentification sdk

Gérer les clés REST API

Vous pouvez afficher les détails ou supprimer les clés REST API existantes depuis Paramètres > API et identifiants > onglet Clés API. Notez que vous ne pouvez pas modifier les clés REST API après les avoir créées.

L’onglet Clés API comprend les informations suivantes pour chaque clé :

Pour afficher les détails d’une clé API, survolez la clé et sélectionnez Voir. Cela inclut toutes les permissions de cette clé, les adresses IP autorisées (le cas échéant), et si cette clé est inscrite au système d’autorisation IP de Braze.

Notez que lors de la suppression d’un utilisateur, Braze ne supprime pas les clés API associées que cet utilisateur a créées. Pour supprimer une clé, survolez-la et sélectionnez Supprimer.

Sécurité des clés REST API

Les clés API sont utilisées pour authentifier un appel API. Lorsque vous créez une nouvelle clé REST API, vous devez lui accorder l’accès à des endpoints spécifiques. En attribuant des permissions spécifiques à une clé API, vous pouvez limiter précisément les appels qu’une clé API peut authentifier.

Étant donné que les clés REST API permettent l’accès à des endpoints REST API potentiellement sensibles, sécurisez ces clés et ne les partagez qu’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 pas de toute autre manière publique.

Une bonne pratique de sécurité consiste à n’accorder à un utilisateur que l’accès nécessaire à l’accomplissement de ses tâches : ce principe peut également être appliqué aux clés API en attribuant des permissions à chaque clé. Ces permissions vous offrent une meilleure sécurité et un meilleur contrôle sur les différentes zones de votre compte.

Avertissement

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

Si vous exposez accidentellement une clé, vous pouvez la supprimer depuis la console de développement. Pour obtenir de l’aide avec ce processus, ouvrez un ticket de support.

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

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

Mise en liste d’autorisation des adresses IP pour l’API

Pour une sécurité renforcée, vous pouvez spécifier une liste d’adresses IP et de sous-réseaux autorisés à effectuer des requêtes REST API pour une clé REST API donnée. C’est ce qu’on appelle la mise en liste d’autorisation (ou whitelisting). Pour autoriser des adresses IP ou des sous-réseaux spécifiques, ajoutez-les à la section Whitelist IPs lors de la création d’une nouvelle clé REST API :

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

Conseil

Si vous effectuez un webhook Braze-à-Braze et utilisez la mise en liste d’autorisation, consultez la liste des adresses IP à autoriser.

Authentification et sécurité de l’API

Authentification par jeton Bearer

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

1
Authorization: Bearer YOUR_REST_API_KEY

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

1. Validité du jeton : Vérifie que la clé API REST existe dans Braze et qu’elle est active (par exemple, qu’elle n’est pas révoquée ou désactivée).
2. Autorisation du jeton : Confirme que la clé API dispose des permissions requises pour l’endpoint demandé.

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

Casse des en-têtes de requête

Les noms d’en-têtes HTTP sont insensibles à la casse, donc Authorization et authorization sont équivalents. Il en va de même pour les autres en-têtes de requête standard, comme Content-Type. Envoyez la casse produite par votre client HTTP.

Braze accepte également toute casse du schéma Bearer (Bearer, bearer ou BEARER). Envoyez la clé API REST exactement telle qu’elle a été émise.

Sécurité au niveau du réseau

Les requêtes de l’API REST vers Braze sont protégées par le chiffrement TLS (Transport Layer Security) sur l’ensemble du chemin de la requête. Le tableau suivant décrit le flux réseau d’une requête API depuis 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 à travers le NLB vers le NGINX ingress, de sorte que votre clé API et les données de requête restent chiffrées en transit.

Ressources supplémentaires

Bibliothèque client Ruby

Si vous déployez Braze en utilisant Ruby, vous pouvez utiliser la bibliothèque client Ruby pour réduire votre temps d’importation de données. Une bibliothèque client est une collection de code spécifique à un langage de programmation — dans ce cas, Ruby — qui facilite l’utilisation d’une API.

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

Important

Cette bibliothèque client est en version bêta. Pour nous aider à l’améliorer, envoyez vos commentaires à [email protected].