Migrate an API key integration to a private app

Si vous voyez une bannière dans votre compte pour désactiver votre clé d'API :

  • Les clés d'API de développeur sont distinctes des clés d'API HubSpot standards et ne sont pas obsolètes. Les clés d'API pour développeurs sont utilisées pour gérer les paramètres liés à vos applications HubSpot, notamment les abonnements à l'API de webhooks et les types d'événements de l'API des événements de la chronologie.

Si vous avez créé une intégration interne qui utilise une clé d'API HubSpot, votre clé d'API fournit à la fois un accès en lecture et en écriture à toutes vos données de CRM HubSpot, ce qui peut constituer un risque de sécurité si votre clé d'API est corrompue. En migrant vers une application privée, vous pouvez autoriser les domaines spécifiques dont votre intégration a besoin, ce qui génère un jeton d'accès qui limite les données que votre intégration peut demander ou modifier dans votre compte.

Suivez les étapes ci-dessous pour migrer une intégration de clé d'API existante vers une application privée. Il est recommandé d'utiliser d'abord un environnement de test, tel qu'un compte de test développeur ou un compte sandbox, avant d'apporter des modifications en production. Si vous avez des questions lors de la migration de votre application, consultez la communauté des développeurs. 

Pour une présentation vidéo de la migration d'une intégration de clé d'API vers une application privée, consultez la vidéo ci-dessous pour les développeurs HubSpot :

Dans ce guide

Remarque : Les applications privées ne prennent pas en charge les webhooks et certains types d'extensions. Si votre intégration existante utilise l'une de ces fonctionnalités, vous devez créer une application publique via OAuth à la place.

Créer une nouvelle application privée

  • Dans votre compte HubSpot, cliquez sur l'icône Paramètres dans la barre de navigation principale.
  • Dans le menu latéral de gauche, accédez à Intégrations > Applications privées.
  • Cliquez sur Créer une application privée.
  • Dans l'onglet Informations de base, configurez les détails de votre application :
    • Saisissez le nom de votre application.
    • Passez le curseur de la souris sur le logo de variable et cliquez sur l'icône de téléchargement pour télécharger une image carrée qui servira de logo pour votre application.
    • Saisissez une description pour votre application.
  • Cliquez sur l'onglet Domaines.
  • Puis, sélectionnez les domaines à autoriser en fonction des API que votre intégration utilise. Pour identifier les domaines dont votre application aura besoin :
    • Compilez une liste des API HubSpot que votre intégration existante utilise.
    • Pour chaque demande d'API, accédez à la documentation de développeur associée (par exemple, API de contacts).
    • Cliquez sur l'onglet Points de terminaison, puis faites défiler jusqu'au point de terminaison utilisé par votre intégration.
    • Dans la section Exigences, identifiez les domaines requis pour utiliser le point de terminaison. Dans la mesure du possible, vous devez opter pour les domaines répertoriés sous Domaines granulaires au lieu de ceux listés sous Domaines standard. Si aucun domaine granulaire n'est répertorié, utilisez les domaines standard.locate-scope-in-endpoints-tab-for-private-app-migration
    • De retour dans les paramètres de votre application privée, sélectionnez les cases à cocher Lecture ou Écriture à côté des domaines correspondants. Vous pouvez également rechercher un domaine via la barre de recherche Rechercher un domaine.select-matching-scope-for-private-app
  • Une fois que vous avez sélectionné vos domaines, cliquez sur Créer une application dans l'angle supérieur droit. Vous pourrez toujours apporter des modifications à votre application après l'avoir créée.
  • Dans la boîte de dialogue, vérifiez les informations sur le jeton d'accès de votre application, puis cliquez sur Continuer de créer.

Une fois votre application privée créée, vous pouvez commencer à effectuer des demandes d'API via son jeton d'accès. Dans l'onglet Détails de la page des paramètres de votre application privée, cliquez sur Afficher le jeton sous votre jeton d'accès pour le révéler.

show-private-app-access-token-migration-guide

Mettre à jour la méthode d'autorisation des demandes d'API de votre intégration

Au lieu d'utiliser un paramètre de demande hapiKey pour effectuer des demandes d'API, des jetons d'accès d'application privée sont inclus dans l'en-tête Authorization de votre demande. Lorsque vous effectuez une demande, définissez la valeur de l'en-tête Authorization sur Bearer VOTRE_JETON. Sauf indication contraire, cette méthode d'autorisation est compatible avec tous les points de terminaison des API publiques, y compris les API existantes répertoriées dans l'ancienne documentation de HubSpot pour les développeurs.

Votre demande peut ressembler à ce qui suit :

axios.get('https://api.hubapi.com/crm/v3/objects/contacts', { headers: { 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );$headers = [ 'Content-Type: application/json', 'Authorization: Bearer ' . YOUR_ACCESS_TOKEN, ]; $curl = curl_init(); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); curl_setopt($curl, CURLOPT_URL, 'https://api.hubapi.com/crm/v3/objects/contacts'); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $contacts = curl_exec($curl); curl_close($curl); var_dump($contacts);require 'uri' require 'net/http' require 'openssl' url = URI("https://api.hubapi.com/crm/v3/objects/contacts") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Get.new(url) request['content-type'] = 'application/json' token = 'YOUR_ACCESS_TOKEN' request['authorization'] = "Bearer #{token}" response = http.request(request) puts response.read_bodyimport requests url = "https://api.hubapi.com/crm/v3/objects/contacts" headers = { 'content-type': 'application/json', 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } response = requests.request("GET", url, headers=headers) print(response.text)

Les jetons d'accès des applications privées sont implémentés sur OAuth. Ainsi, vous pouvez également effectuer des appels authentifiés avec votre jeton d'accès à l'aide de l'une des bibliothèques clientes de HubSpot. Par exemple, si vous utilisez la bibliothèque cliente Node.js, vous pouvez instancier un client OAuth en transmettant le jeton d'accès de votre application : 

const hubspotClient = new hubspot.Client({ accessToken: YOUR_ACCESS_TOKEN }); $hubSpot = \HubSpot\Factory::createWithAccessToken('access-token'); $response = $hubSpot->crm()->contacts()->basicApi()->getPage();# Load the gem require 'hubspot-api-client' # Setup client client = Hubspot::Client.new(access_token: 'YOUR_ACCESS_TOKEN') # Get contacts contacts = client.crm.contacts.basic_api.get_pagefrom hubspot import HubSpot api_client = HubSpot(access_token='YOUR_ACCESS_TOKEN') api_client.crm.contacts.get_page()

Pour terminer la migration vers votre application privée, supprimez toutes les références à la clé d'API HubSpot de votre code et utilisez plutôt l'approche ci-dessus pour utiliser le jeton d'accès de votre application privée. En fonction de la demande effectuée, vous pouvez créer un secret pour stocker votre jeton, plutôt que de le coder en dur dans vos demandes. L'utilisation d'un secret empêchera votre jeton d'être exposé, comme lors de l'utilisation d'un jeton dans une fonction sans serveur. Pour stocker le jeton d'accès en tant que secret :

  • Dans le terminal, exécutez hs secrets add secretName. Il est recommandé de nommer le secret simplement afin que vous puissiez facilement le mentionner ultérieurement.
  • Collez le jeton d'accès dans le terminal, puis appuyez sur Entrée.

Vous pouvez ensuite accéder à votre secret en tant que variable d'environnement. Découvrez-en davantage dans l'exemple des fonctions sans serveur ci-dessous.

Pour vérifier que toutes les références à votre clé d'API ont été supprimées, vous pouvez consulter le journal des appels dans votre compte HubSpot :

  • Dans votre compte HubSpot, cliquez sur l'icône Paramètres dans la barre de navigation principale.
  • Dans la barre latérale de gauche, accédez à Intégrations > Clé d'API.
  • Consultez les demandes les plus récentes dans l'onglet Journal des appels pour vérifier qu'aucune demande récente n'a été effectuée depuis la suppression de toutes les références précédentes pour utiliser le jeton d'accès de votre application privée.

check-api-key-call-log-after-migration

Si vous disposez d'un compte Marketing Hub payant avec des contacts marketing et que vous avez précédemment défini des contacts créés par des intégrations utilisant votre clé d'API comme contacts marketing, vous devez également faire de même pour votre application privée :

  • Dans votre compte HubSpot, cliquez sur l'icône Paramètres dans la barre de navigation principale.
  • Dans la barre latérale de gauche, accédez à Intégrations> Contacts marketing.
  • Sous Vos applications connectées, utilisez la barre de recherche pour trouver votre application privée, puis cliquez sur Activer pour synchroniser des contacts comme contacts marketing.

set-private-app-contacts-as-marketing-contacts

Une fois que vous avez configuré votre application privée et vérifié que toutes les références à votre clé d'API ont été supprimées dans votre code, vous pouvez désactiver la clé.

Vérifier les demandes et suivre les journaux

Une fois que vous avez supprimé toutes les références à la clé d'API HubSpot dans votre code et que vous les avez remplacées par des références au jeton d'accès de votre application privée, aucune autre modification de code n'est requise.

Si vous avez suivi les étapes ci-dessus dans un compte de test développeur ou sandbox, répétez le même processus dans votre compte de production. Ensuite, suivez les journaux d'appels d'API de votre application privée et vérifiez qu'aucune des demandes de votre application ne renvoie d'erreurs 400 :

  • Dans votre compte HubSpot, cliquez sur l'icône Paramètres dans la barre de navigation principale.
  • Dans le menu latéral de gauche, accédez à Intégrations > Applications privées.
  • Cliquez sur le nom de votre application privée.
  • Cliquez sur l'onglet Journaux.
  • Toute demande d'API ayant échoué en raison d'un domaine manquant apparaîtra comme une erreur 403. Si vous accédez aux journaux d'exécution de votre intégration, la réponse de la demande d'API correspondante doit inclure un message d'erreur avec des détails sur les domaines manquants.

403-error-after-private-app-migration

  • Si vous devez inclure un nouveau domaine pour votre application privée :
    • Cliquez sur l'onglet Détails.
    • Cliquez sur Modifier les détails.
    • En haut de la page, cliquez sur Domaines.
    • Sélectionnez la case à cocher à côté des domaines manquants, puis cliquez sur Engager les modifications dans l'angle supérieur droit lorsque vous avez terminé.

select-missing-scopes-private-app-migration

Découvrez-en davantage sur la création et la gestion d'applications privées ainsi que sur leurs limites dans le guide des applications privées.

Exemples d'implémentation

Découvrez ci-dessous les utilisations courantes des clés d'API et la migration vers des jetons d'accès d'application privée.

Fonctions sans serveur

Si vous utilisez une clé d'API dans une fonction sans serveur, vous pouvez également utiliser le jeton d'accès de l'application privée pour l'authentification. Vous devrez vous assurer que l'application privée dispose des domaines nécessaires pour que la fonction s'exécute. 

Pour authentifier une fonction sans serveur avec un jeton d'accès d'application privée :

  • Sur la carte Jeton d'accès, cliquez sur Afficher le jeton pour afficher votre jeton d'accès. Cliquez ensuite sur Copier pour copier le jeton dans le presse-papiers.
    show-private-app-access-token-1
  • Une fois votre jeton d'accès copié, créez un nouveau secret pour stocker le jeton :
    • Dans le terminal, exécutez hs secrets add secretName. Il est recommandé de nommer le secret simplement afin que vous puissiez facilement le mentionner ultérieurement.
    • Collez le jeton d'accès dans le terminal, puis appuyez sur Entrée.
  • Dans le fichier serverless.json de votre fonction sans serveur, ajoutez le nom du secret au tableau secret :
// example serverless.json file { "runtime": "nodejs18.x", "version": "1.0", "secrets": ["secretName"], "endpoints": { "getPrompts": { "method": "GET", "file": "serverlessFunction.js" } } }
  • Dans le fichier JavaScript de votre fonction sans serveur, définissez la valeur de l'en-tête Authorization sur Bearer secretName. Par exemple, si vous effectuez un appel vers l' API de contacts via Node.js et axios, la demande ressemblera à ceci :
// example serverless function const axios = require('axios'); exports.main = (context, sendResponse) => { axios.get(`https://api.hubapi.com/crm/v3/objects/contacts`, { headers: { 'Authorization': `Bearer ${process.env.secretName}`, 'Content-Type': 'application/json' } } ) sendResponse({statusCode: 200}); };

Découvrez comment passer des appels d'API avec le jeton de votre application.

Tâches ponctuelles

Si vous utilisez une clé d'API pour exécuter des tâches ponctuelles, telles que la création d'une propriété, vous pouvez créer une application privée et utiliser son jeton d'accès pour authentifier l'appel à la place. Une fois qu'une application privée est créée, vous pouvez réutiliser son jeton d'accès pour n'importe quelle tâche ponctuelle, tant que l'application privée dispose des domaines appropriés. Vous pouvez mettre à jour les domaines d'une application privée à tout moment depuis les paramètres de l'application privée dans HubSpot. Vous pouvez également supprimer l'application privée et en créer une nouvelle spécifique à la tâche à exécuter.

private-app-edit-scopes

Créer des objets personnalisés

Au lieu d'utiliser une clé d'API pour créer un objet personnalisé, vous pouvez créer une application privée et utiliser son jeton d'accès pour authentifier l'appel, tant que l'application dispose des domaines nécessaires. Par exemple, lorsque vous utilisez Postman pour créer un objet personnalisé, définissez le type d'autorisation sur Jeton Bearer, puis saisissez le jeton dans le champ Jeton.

postman-private-app-access-token-field

Découvrez-en davantage sur la création d'un objet personnalisé à l'aide d'une application privée sur le blog pour les développeurs de HubSpot.

Actions de workflow à code personnalisé

Si vous utilisez une clé d'API dans une action de workflow à code personnalisé, vous pouvez utiliser le jeton d'accès de l'application privée, tant que l'application dispose desdomaines nécessaires. Pour effectuer la mise à jour, ouvrez l'action personnalisée dans l'éditeur de workflow, puis effectuez les mises à jour suivantes :

const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName });
Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.