Travailler avec OAuth

OAuth est une méthode d'authentification sécurisée qui utilise des jetons d'autorisation plutôt qu'un mot de passe pour connecter votre application à un compte utilisateur. Le lancement de l'accès OAuth est la première étape pour permettre aux utilisateurs d'installer votre application dans leurs comptes HubSpot.

Remarque pour tous les développeurs d'applications : Toute application conçue pour une installation par plusieurs comptes HubSpot ou pour un listing sur le marketplace des applications doit utiliser OAuth. Si vous utilisez une clé d'API, votre listing d'application sera rejeté. 

Ressources recommandées
  • Le Guide de démarrage rapide pour OAuth vous offrira davantage d'informations avec un exemple d'application.
  • Ce tutoriel HubSpot Academy propose une présentation rapide quant à l'utilisation d'OAuth avec HubSpot, y compris une répartition du flux HubSpot-OAuth et des explications sur l'actualisation d'un jeton d'accès.

Lancer une intégration avec OAuth 2.0

1. La première étape pour l'utilisation d'OAuth consiste à créer une application dans un compte de développeur HubSpot. Pour cela, vous trouverez l'ID du client et le secret client pour votre application sur la page d'authentification de vos paramètres d'application.

MyHubSpotApp

 

2. Utilisez l'ID du client et le secret client ainsi que les paramètres de requête et les domaines décrits ci-dessous pour créer votre URL d'autorisation. 

3. Envoyez les utilisateurs qui installent votre application vers l'URL d'autorisation, où ils verront un écran qui leur permettra de sélectionner un compte (s'ils disposent de plusieurs comptes) et d'autoriser l'accès à votre intégration. Après avoir autorisé l'accès, ils seront redirigés vers votre demande via redirect_url, qui sera associé à un paramètre de requête de code. Vous utiliserez ce code et le secret client pour obtenir un jeton d'accès et un jeton d'actualisation depuis HubSpot.

Exemple d'URL d'autorisation

https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/

Exemple d'URL de redirection

https://www.exemple.com/?code=xxxx

Exemple d'erreur

https://www.exemple.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error

 

4. Utilisez le jeton d'accès pour authentifier tous les appels d'API effectués pour ce compte HubSpot.

5. Une fois que le jeton d'accès expire, utilisez le jeton d'actualisation de l'étape 3 pour générer un nouveau jeton d'accès.


Remarque : Votre application ne s'affichera pas comme une application connectée dans les paramètres d'intégration de l'utilisateur tant que vous ne réaliserez pas les deux premières étapes. Vous devez générer le jeton d'actualisation et le jeton d'accès initial pour que l'application apparaisse comme connectée.


Paramètres de requête

Ces paramètres sont obligatoires lors de la création d'une URL d'autorisation pour votre compte :

 

Paramètres obligatoires
Paramètre obligatoire Description Fonctionnement
ID du client client_id=x
Utilisé dans l'URL
Obtenez cela depuis la page des paramètres d'authentification de votre application (telle que décrite ci-dessus).
URL de redirection redirect_uri=x
L'URL vers laquelle seront redirigés les visiteurs après avoir accordé l'accès à votre application. 
Vous pouvez également désigner cette page sur la page des paramètres d'authentification de votre application. Remarque : Pour des raisons de sécurité, cette URL doit utiliser HTTPS en production (lorsque vous effectuez un test avec localhost, HTTP peut être utilisé). Vous devez également utiliser un domaine, car les adresses IP ne sont pas prises en charge.
Domaine scope=x%20x Un ensemble d'autorisations séparées par des espaces auxquelles votre application doit avoir accès. Tous les domaines que vous avez vérifiés dans les paramètres d'authentification de votre application seront considérés comme obligatoires et vous devrez les inclure dans ce paramètre. Autrement, la page d'autorisation affichera une erreur. En outre, les utilisateurs recevront une erreur s'ils tentent d'installer votre application sur un compte qui n'a pas accès à un domaine inclus.
Consultez le tableau Domaines ci-dessous pour en savoir plus sur les points de terminaison disponibles pour des domaines spécifiques.

 

Voici les éléments facultatifs :

 

Paramètres facultatifs
Paramètre facultatif Fonctionnement Description
Domaines facultatifs &optional_scope=x%20x Un ensemble d'autorisations séparées par des espaces pour votre application. Les domaines facultatifs seront automatiquement supprimés de la demande d'autorisation si l'utilisateur sélectionne un compte HubSpot qui n'a pas accès à cet outil (par exemple, la demande du domaine social sur un CRM uniquement). Si vous utilisez des domaines facultatifs, vous devez vérifier le jeton d'accès ou le jeton d'actualisation pour consulter ceux qui ont été accordés. Consultez le tableau ci-dessous pour en savoir plus sur les domaines.
État &state=y
Si ce paramètre est inclus dans l'URL d'autorisation, la valeur sera incluse dans un paramètre de requête d'état lorsque l'utilisateur sera dirigé vers redirect_url.
Une valeur de chaîne pouvant être utilisée pour maintenir l'état de l'utilisateur lorsqu'il est redirigé vers votre application. 

 

Domaines

OAuth exige que vous définissiez des domaines, ou des autorisations, pour votre application. Chaque domaine fournit un accès à un ensemble de points de terminaison d'API HubSpot et permet aux utilisateurs d'accorder à votre application l'accès à des outils spécifiques dans leur compte HubSpot. 

Screen Shot 2020-03-26 at 4.21.46 PM

L'accès à des API ou points de terminaison spécifiques dépend du niveau de compte HubSpot. Vous pouvez trouver une liste complète des domaines disponibles et des points de terminaison accessibles dans le tableau ci-dessous. Si votre application peut fonctionner avec plusieurs types de comptes HubSpot, vous pouvez utiliser le paramètre optional_scope pour inclure des domaines de travail. Ainsi, les clients utilisant uniquement des comptes de CRM peuvent toujours autoriser votre application, même s'ils ne peuvent pas accéder à tous ses domaines. Votre application doit vérifier et traiter tous les domaines pour lesquels elle ne reçoit pas d'autorisation.

 

Tous les domaines
 Domaine Description Donne accès à Niveau de compte requis
automation Comprend les workflows. API Automatisation (points de terminaison des workflows) Hub Marketing Pro ou Entreprise
business-intelligence Comprend les points de terminaison situés sur les sources et les e-mails. API Analytics Tout compte
contacts Comprend les contacts et les listes. Points de terminaison des contacts, des entreprises, des transactions, des propriétés, des engagements et des propriétaires Tout compte
content Comprend les sites, les pages de destination, le CTA, les e-mails, les blogs et les campagnes. Points de terminaison de l'API CMS et du calendrier, des e-mails et des événements par e-mail Hub CMS Pro ou Entreprise, ou Hub Marketing Pro ou Entreprise
conversations.visitor_identification.tokens.create  Récupérez des jetons d'identification pour les visiteurs de sites web authentifiés qui interagissent avec le widget de chat HubSpot. API Identification des visiteurs Pro ou Entreprise
crm.import Vous permet d'importer des fiches d'informations dans votre CRM. Cela inclut la création de nouvelles fiches d'informations ou la modification de vos fiches d'informations existantes pour tous les types de données du CRM (contacts, entreprises, transactions, tickets, etc.). Cela n'inclut pas l'archivage ou la suppression de données. API Imports de CRM Tout compte
cms.source_code.read_write Permet de charger et de télécharger des modèles, des modules et d'autres fichiers dont les développeurs ont besoin pour écrire du code pour des sites web et des e-mails. API Mappeur de fichiers de contenu, API Modules CMS, mises en page CMS, API Modèles CMS Hub CMS Pro ou Entreprise, ou Hub Marketing Pro ou Entreprise
e-commerce Comprend l'accès aux fonctionnalités de e-commerce. Points de terminaison des produits et des lignes de produit Hub Sales Pro ou Entreprise

Remarque : Les utilisateurs doivent disposer d'une licence Hub Sales payante pour autoriser ce champ.
files Comprend l'accès au gestionnaire de fichiers. Points de terminaison des fichiers (gestionnaire de fichiers) et du mappeur de fichiers (modèles, modules et mises en page CMS) Tout compte
forms Comprend l'accès aux points de terminaison des formulaires. Points de terminaison des formulaires

Remarque : L'accès aux formulaires nécessite également le domaine contacts.
Tout compte
forms-uploaded-files Téléchargez des fichiers soumis via un formulaire. Obtenir un fichier chargé via le point de terminaison de soumission de formulaire Tout compte
hubdb Comprend l'accès à HubDB. Points de terminaison HubDB Hub CMS Pro ou Entreprise, ou Hub Marketing Pro ou Entreprise avec module complémentaire CMS
integration-sync Expose l'API de synchronisation, qui permet la synchronisation de la plupart des objets de CRM.  API Bridge e-commerce Tout compte
oauth Le domaine de base nécessaire pour OAuth.   Tout compte
sales-email-read Permet d'accéder à tous les détails des e-mails individuels envoyés aux contacts. Points de terminaison des engagements

Remarque : Ce domaine est obligatoire pour obtenir le contenu d'engagements par e-mail. Consultez la vue d'ensemble des engagements pour plus de détails.
Hub Sales Gratuit, Starter, Pro ou Entreprise
social Comprend la boîte de réception des réseaux sociaux. API Réseaux sociaux Hub Marketing Pro ou Entreprise
tickets Comprend l'accès aux tickets. Points de terminaison des tickets Hub Services Gratuit, Starter, Pro ou Entreprise
timeline Permet d'accéder à la gestion d'activités personnalisées sur les fiches d'informations du HubSpot CRM. Cela inclut la création ou la mise à jour des fiches d'informations. Points de terminaison des événements chronologiques Tout compte
transactional-email Comprend les e-mails transactionnels et les points de terminaison des e-mails transactionnels. Points de terminaison des e-mails transactionnels Hub Marketing Pro ou Entreprise avec module complémentaire E-mails transactionnels

 


Documents associés

Méthodes d'authentification sur HubSpot

Guide de démarrage rapide pour OAuth

Gestion des jetons