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é. Si vous n’êtes pas sûr, 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-le 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 limite de 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 afin de 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 : L’external_id sert d’identifiant unique pour l’utilisateur 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 API REST

Une clé API REST (clé d’interface de programmation d’applications REST) 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 utilisant des requêtes web HTTPS vers l’endpoint REST API 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 afin de s’assurer 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 pouvez le constater, ces espaces de travail utilisent également la REST API et disposent de leurs propres clés API REST. Ces clés peuvent être individuellement limitées 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é API REST et la clé API d’espace de travail sous le nom api_key. La api_key est incluse dans chaque requête en tant qu’en-tête de requête et sert de clé d’authentification qui vous permet 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é API REST, 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 API REST, 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 les applications, les modèles, les Canvas, les Campaigns, les Content Cards et les Segments depuis l’API. Pour plus d’informations, consultez Types d’identifiants API.

Créer des clés API REST

Pour créer une nouvelle clé API REST :

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 d’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 API REST

Les permissions de clé API sont des permissions 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é API, allez dans Paramètres > API et identifiants, et sélectionnez votre clé API.

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

Gérer les clés API REST

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

L’onglet Clés API inclut 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 activée pour la liste 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 clé et sélectionnez Supprimer.

Sécurité des clés API REST

Les clés API sont utilisées pour authentifier un appel API. Lorsque vous créez une nouvelle clé API REST, 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 API REST 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 d’aucune 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 un meilleur contrôle de la sécurité sur les différentes zones de votre compte.

Avertissement

Étant donné que les clés API REST 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 d’aucune 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 API REST et des clés API SDK

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

Liste d’autorisation 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é API REST donnée. C’est ce qu’on appelle la liste d’autorisation (allowlisting ou whitelisting). Pour autoriser des adresses IP ou des sous-réseaux spécifiques, ajoutez-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 vers Braze et utilisez une 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’a pas été 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 ne sont pas sensibles à la casse, donc Authorization et authorization sont équivalents. Il en va de même pour les autres en-têtes de requête standard, tels que Content-Type. Envoyez la casse que votre client HTTP produit.

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 (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 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 la requête restent chiffrées en transit.

Ressources supplémentaires

Bibliothèque client Ruby

Si vous déployez 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 un ensemble 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].