Overview API

Cet article de référence couvre les bases de l’API, y compris la terminologie commune et un aperçu des clés de l’API REST, des permissions 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 créé, veuillez vous connecter à l’une des URL suivantes. Utilisez le bon Endpoint REST en vous basant sur l’instance qui vous a été provisionné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. Veuillez vous connecter à Braze et accédez à Paramètres > API et identifiants > clés API.
2. Veuillez sélectionner une clé API existante ou choisir Créer une clé API pour générer une nouvelle clé.
3. Veuillez copier l’endpoint REST affiché dans cet onglet et l’utiliser pour vos requêtes API.

Limites de l’API

Pour la plupart des API, la limite de débit par défaut définie par Braze est 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 clientèle. Consultez les limites de débit de l’API](/docs/fr/api/api_limits/) pour plus d’informations

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.
• Identifiant utilisateur Braze :braze_idsert d’identifiant utilisateur unique défini par Braze. Vous pouvez utiliser cet identifiant pour supprimer des utilisateurs via l’API REST, en plus de 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 est un code unique que vous transmettez à une API afin d’authentifier l’appel API et d’identifier l’application ou l’utilisateur à l’origine de l’appel. Vous pouvez accéder à l’API en utilisant 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 afin de garantir le bon fonctionnement de l’ensemble du système.

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 personnalisées individuellement pour inclure l’accès à des endpoints spécifiques sur l’API. Chaque appel à l’API doit inclure une clé ayant accès à l’endpoint.

Nous faisons référence à la clé API REST et à la clé API de l’espace de travail en tant que api_key. Le api_key est inclus dans chaque requête en tant qu’en-tête de requête et agit comme une clé d’authentification qui vous permet 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, il est nécessaire de lui accorder l’accès à des endpoints spécifiques. En affectant des autorisations spécifiques à une clé API, vous pouvez limiter de façon précise les appels qu’une clé API peut authentifier.

Créer des clés API REST

Pour créer une nouvelle clé d’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écifier les sous-réseaux et adresses IP autorisés pour cette nouvelle clé.
5. Sélectionnez les autorisations que vous souhaitez associer à votre nouvelle clé.

Autorisations de clé API REST

Les autorisations de clés API sont des autorisations 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 Paramètres > API et identifiants, 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 à partir de Paramètres > API et identifiants > onglet Clés API. Veuillez noter que vous ne pouvez pas modifier les clés API REST une fois qu’elles ont été créées.

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

Pour afficher les détails d’une clé API, passez la souris sur la clé et sélectionnez View. Cela comprend toutes les autorisations dont dispose cette clé, les adresses IP inscrites sur la liste blanche (le cas échéant) et si cette clé est inscrite sur la liste blanche des adresses IP de Braze.

Veuillez noter 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 Supprimer.

Sécurité clé API REST

Les clés API servent à authentifier les appels de l’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 de façon précise les appels qu’une clé API 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 faire des appels AJAX depuis votre site Web ou pour l’exposer autrement de façon publique.

Une bonne pratique de sécurité est d’accorder à un utilisateur uniquement les accès nécessaires pour qu’il puisse accomplir son travail ; ce principe peut également être appliqué aux Clés API en affectant des autorisations pour chaque clé. Ces autorisations vous offrent une meilleure sécurité et un meilleur contrôle sur les différentes parties de votre compte.

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

Liste d’adresses IP autorisées

Pour renforcer la sécurité, vous pouvez établir une liste des adresses IP et sous-réseaux qui sont exclusivement autorisés à envoyer des requêtes à l’API REST pour une clé API REST donnée. Vous définissez pour cela une liste d’autorisations, également appelée « Liste blanche ». Pour autoriser des adresses IP ou des sous-réseaux spécifiques, indiquez-les dans la section **Liste blanche d’adresses IP (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.

Authentification et sécurité API

Authentification par jeton au porteur

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

1
Authorization: Bearer YOUR_REST_API_KEY

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

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 par 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 Unauthorizedcela indique une clé non valide ou manquante, tandis que403 Forbiddencela indique que la clé ne dispose pas des autorisations nécessaires pour l’endpoint demandé. Pour plus d’informations, veuillez consulter la section Erreurs API.

Sécurité au niveau du réseau

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

La sécurité de la couche de transport 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’entrée NGINX, de sorte que votre clé API et vos données de requête restent cryptées pendant leur transfert.

Ressources complémentaires

Bibliothèque client Ruby

Si vous implémentez Braze à l’aide de Ruby, vous pouvez utiliser la bibliothèque cliente Ruby pour réduire le temps d’importation de vos données. Une bibliothèque cliente 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 utilisateur.