Comment créer ou cloner une clé d’API privée

Objectif de cet article

Découvrez comment créer ou cloner une clé d’API privée et choisir des portées qui contrôlent ce à quoi une application peut accéder dans votre compte Klaviyo.

Les clés d’API privées et les portées vous aident toutes deux à protéger vos données et celles de vos clients en limitant ce à quoi des tiers peuvent accéder.

À propos des clés d’API privées et des champs d’application

Un appel API permet à une application de demander, d’ajouter, ou de modifier des informations dans une autre application.

Une clé d’API privée identifie votre compte Klaviyo, et autorise les requêtes d’API à l’aide des portées attribuées à la clé. Toute personne disposant de la clé peut utiliser ces autorisations, alors traitez-la comme un mot de passe.

L’inclusion d’un champ d’application pour une clé d’API privée ajoute un niveau d’autorisation supplémentaire, en limitant les éléments spécifiques auxquels un tiers peut accéder. Les autorisations sont similaires à une clé d’hôtel : elles vous donnent uniquement accès à certaines zones (comme votre chambre ou la salle de sport), et non à l’ensemble du bâtiment.

Niveaux d’accès du périmètre

Lorsque vous créez une clé d’API privée, choisissez un niveau d’accès pour chaque champ d’application de l’API. Ces niveaux d’accès déterminent si une partie tierce peut :

• Ne pas avoir accès aux données ou aux actions couvertes par cette portée.
• Consultez les données couvertes par cette portée sans effectuer de modifications (accès en lecture).
• Afficher les données et créer, supprimer ou effectuer d’autres modifications couvertes par cette portée (accès en lecture/écriture).

Par exemple, pour abonner des profils au marketing et les ajouter à une liste Klaviyo depuis une autre application, utilisez Abonner des profils en masse. Ce point de terminaison nécessite lists:write, profiles:write et subscriptions:write. L’octroi d’un accès en lecture/écriture pour ces portées couvre cette demande ; vous n’avez pas besoin d’accorder l’accès à des portées non liées.

Vous pouvez en savoir plus sur les API de Klaviyo et consulter les autorisations disponibles pour chaque points de terminaison sur le portail de développement.

Avant de commencer

Veuillez noter les éléments suivants :

• Après avoir créé une clé d’API privée, vous ne pouvez pas :
  • Affichez à nouveau la clé d’API privée complète après avoir quitté sa page de confirmation.
    • Conseil : enregistrez de manière sécurisée les clés d’API privées et notez à quoi vous souhaitez les utiliser, par exemple dans un gestionnaire de mots de passe.
  • Ajouter ou modifier ses portées.
    • Si vous avez besoin d’autorisations différentes, créez une nouvelle clé d’API privée avec l’accès requis. Mettez à jour toutes les intégrations qui utilisent l’ancienne clé, et confirmez qu’elles fonctionnent avant de la supprimer.
• La page de création s’ouvre avec Clé personnalisée sélectionnée. Choisissez l’accès à au moins 1 champ d’application de l’API avant de créer la clé.

Si vous ne savez pas quels points de terminaison, champs d’application ou autorisations d’API vous avez besoin, veuillez contacter un développeur ou faire appel à un partenaire Klaviyo pour obtenir de l’aide.

Créer une clé d’API privée

1. Cliquez sur le nom de votre organisation en bas à gauche.
2. Accédez à Paramètres.
3. Click clé d’API.
   

4. Cliquez sur Créer une clé d’API privée.
5. Nommez la clé d’API.
6. Sous Sélectionner le niveau d’accès, choisissez l’accès dont vos intégrations ont besoin :
   • Clé en lecture seule: accorde un accès en lecture pour tous les champs d’application de l’API disponibles.
   • Clé d’accès complet: accorde un accès en lecture/écriture à tous les champs d’application de l’API disponibles.
   • Clé personnalisée: vous permet de choisir Aucun accès, Accès en lecture ou Accès en lecture/écriture pour chaque ligne sous Champs d’application de l’API. Sélectionnez l’accès à au moins un champ d’application.

7. Sélectionnez Créer.
8. Sur la page de confirmation, utilisez l’icône de copie (Copier la clé) ou l’icône de téléchargement (Télécharger (.txt)) pour enregistrer la clé dans un endroit sécurisé. Vous ne pouvez plus consulter la clé complète après avoir quitté cette page.
9. Sélectionnez Fermer pour revenir aux clés d’API.

Désormais, lorsque vous partagez une clé d’API privée, le tiers n’aura accès qu’aux informations que vous avez définies dans le périmètre.

Cloner une clé d’API privée

Le clonage crée une nouvelle clé d’API privée en utilisant les portées de la clé d’origine. Les portées renommées utilisent leurs noms actuels, et les portées obsolètes sans remplacement sont omises.

Notez cependant que :

• Le clonage ne génère pas la même clé que la clé d’API privée d’origine.
• Une clé d’API clonée porte le même nom que l’originale. Vous ne pouvez pas la renommer dans les paramètres des clés d’API.

Pour cloner une clé d’API privée :

1. Accédez à Paramètres > clés d’API.
2. Cliquez sur le menu à 3 points à côté de la clé que vous souhaitez cloner.
3. Sélectionnez Cloner, puis sélectionnez à nouveau Cloner dans la boîte de dialogue de confirmation.

4. Utilisez l’icône de copie (Copier la clé) ou l’icône de téléchargement (Télécharger (.txt)) pour enregistrer la nouvelle clé dans un endroit sécurisé, puis sélectionnez Fermer. Vous ne pouvez pas afficher à nouveau la clé complète après avoir fermé cette page.
5. Si vous remplacez la clé d’origine, mettez à jour toutes les intégrations qui l’utilisent, et confirmez qu’elles fonctionnent avec la nouvelle clé. Ne supprimez l’originale que lorsqu’elle n’est plus nécessaire.

Utilisation des paramètres de requête

Le paramètre include ajoute des données associées à une réponse d’API. Le paramètre scopes présélectionne des autorisations sur la page de création de clé d’API privée. Il s’agit d’utilisations avancées distinctes des paramètres de requête URL. Si vous ne les connaissez pas, travaillez avec un développeur.

Inclure les données associées dans une réponse API

Lorsqu’un point de terminaison prend en charge le paramètre de requête include, votre clé doit avoir l’autorisation de lire à la fois la ressource demandée et les données associées.

Par exemple, GET /api/profiles/{id}/ récupère un seul profil et nécessite profiles:read. Remplacez {id} par l’ID du profil.

Pour inclure les listes de ce profil, utilisez GET /api/profiles/{id}/?include=lists avec profiles:read et lists:read. Le point de terminaison de la collection de profils (GET /api/profiles/) ne prend pas en charge l’inclusion de listes.

Présélectionner des portées sur la page de création

Ajoutez le paramètre de requête scopes à l’URL de création de la clé d’API privée afin de présélectionner les niveaux d’accès dans le formulaire.

Utilisez une liste de noms de portée séparés par des virgules. Vérifiez l’accès sélectionné, saisissez un nom pour la clé, puis sélectionnez Créer. Copiez ou téléchargez ensuite la clé avant de fermer la page de confirmation.

Un exemple d’URL est :
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write

Accédez à notre portail de développement pour voir les autorisations que vous pouvez utiliser dans cette requête.

Ressources supplémentaires