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 l’endpoint REST correct en fonction de l’instance qui vous a été attribuée. 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 à l’endpoint REST correct.

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 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 dans l’ensemble de la base clients. Pour en savoir plus, consultez les limites de débit de l’API.

ID utilisateur

• ID externe de l’utilisateur : L’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 complément des external_ids.

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

À propos des clés REST API

Une clé REST API (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 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 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 REST API. 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 sollicité.

Nous désignons à la fois la clé REST API et la clé API d’espace de travail sous le terme 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 vous permettant d’utiliser nos REST APIs. Ces REST APIs 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 donner accès à des endpoints spécifiques. En attribuant des permissions spécifiques à une clé API, vous pouvez limiter exactement 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 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 REST API

Pour créer une nouvelle clé REST API :

1. Accédez à Paramètres > API et identifiants.
2. Sélectionnez Créer une clé API.
3. Donnez un nom à votre nouvelle clé pour l’identifier facilement.
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 l’étendue des permissions ni les adresses IP autorisées. Cette limitation est en place pour des raisons de sécurité. Si vous devez modifier l’étendue d’une clé, créez une nouvelle clé avec les permissions mises à jour et implémentez-la à 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 de clé API sont des autorisations que vous pouvez attribuer à un utilisateur ou un groupe pour limiter leur accès à certains appels API. Pour consulter votre liste de permissions de clé API, accédez à 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
• sso
• content blocks
• centre de préférences
• abonnement
• sms
• catalogues
• authentification sdk

Gérer les clés REST API

Vous pouvez consulter les détails ou supprimer des 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 contient 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é a activé 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 créées par cet utilisateur. 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 donner accès à des endpoints spécifiques. En attribuant des permissions spécifiques à une clé API, vous pouvez limiter exactement les appels qu’une clé API peut authentifier.

Étant donné que les clés REST API permettent d’accéder à 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’attribuer à un utilisateur que l’accès nécessaire à l’accomplissement de son travail : 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 d’accéder à 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 concernant ce processus, ouvrez un ticket d’assistance.

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.

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é REST API donnée. C’est ce qu’on appelle la liste d’autorisation (ou liste blanche). Pour autoriser des adresses IP ou sous-réseaux spécifiques, ajoutez-les dans la section IP autorisées 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 créez un webhook Braze-vers-Braze et utilisez la 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 pour l’endpoint demandé. Pour en savoir plus, consultez Erreurs d’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, comme 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 (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 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 à travers le NLB jusqu’au NGINX ingress, de sorte que votre clé API et les données de requête restent chiffrées pendant le transit.

Ressources complé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 contribuer à l’amélioration de cette bibliothèque, envoyez vos commentaires à [email protected].