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 : Toute application conçue pour une installation par plusieurs comptes HubSpot ou pour un listing sur le marketplace des applications doit utiliser OAuth. 

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

Pour lancer une intégration avec OAuth 2.0 :

MyHubSpotApp

  • 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. 
  • 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 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.example.com/?code=xxxx
    • Exemple d'erreur : https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
  • Utilisez le jeton d'accès pour authentifier tous les appels d'API effectués pour ce compte HubSpot.
  • Une fois que access_token expire, utilisez refresh_token pour générer un nouveau access_token.

Remarque : Votre application ne s'affichera pas comme une application connectée dans le compte d'un utilisateur tant que vous ne générerez pas le jeton d'actualisation et le jeton d'accès initial. 

Paramètres de requête

Les paramètres suivants 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.

 

Les paramètres suivants sont 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. 

Périmètres d'accès

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. 

granular-scopes-selection

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.


 Domaine Description Donne accès à Niveau de compte requis
automation Comprend les workflows. API Automatisation (points de terminaison des workflows) Marketing Hub Pro ou Entreprise
business-intelligence Comprend les points de terminaison situés sur les sources et les e-mails. API Analytics Tout compte
collector_graphql_query_execute Demander des données depuis votre compte HubSpot via le point de terminaison d'API GraphQL Point de terminaison d'API GraphQL CMS Hub Pro ou Entreprise
collector_graphql_schema_read Effectuer des demandes d'introspection via des clients d'application GraphQL tels que GraphiQL GraphiQL et autres clients GraphQL tiers  CMS Hub Pro ou Entreprise
crm.lists.read Affichez les détails concernant des listes de contacts. Points de terminaison de liste Tout compte
crm.lists.write Créez, supprimez ou apportez des modifications à des listes de contacts. Points de terminaison de liste Tout compte
crm.objects.companies.read Affichez les propriétés et d'autres détails sur les entreprises. Points de terminaison d'entreprises Tout compte
crm.objects.companies.write Affichez les propriétés et créez, supprimez ou apportez des modifications aux entreprises. Points de terminaison d'entreprises Tout compte
crm.objects.contacts.read Affichez les propriétés et d'autres détails sur les contacts. Points de terminaison des contacts Tout compte
crm.objects.contacts.write Affichez les propriétés et créez, supprimez ou apportez des modifications aux contacts. Points de terminaison des contacts Tout compte
crm.objects.deals.read Affichez les propriétés et d'autres détails sur les transactions. Points de terminaison des transactions Tout compte
crm.objects.deals.write Affichez les propriétés et créez, supprimez ou apportez des modifications aux transactions. Points de terminaison des transactions Tout compte
crm.objects.owners.read Affichez des détails concernant les utilisateurs attribués à une fiche d'informations du CRM. Points de terminaison des propriétaires Tout compte
crm.schemas.companies.read Affichez des détails concernant les paramètres de propriété pour des entreprises. Points de terminaison des propriétés Tout compte
crm.schemas.companies.write Créez, supprimez ou apportez des modifications aux paramètres de propriété concernant des entreprises. Points de terminaison des propriétés Tout compte
crm.schemas.contacts.read Affichez des détails concernant les paramètres de propriété pour des contacts. Points de terminaison des propriétés Tout compte
crm.schemas.contacts.write Créez, supprimez ou apportez des modifications aux paramètres de propriété concernant des contacts. Points de terminaison des propriétés Tout compte
crm.schemas.deals.read Affichez des détails concernant les paramètres de propriété pour des transactions. Points de terminaison des propriétés Tout compte
crm.schemas.deals.write Créez, supprimez ou apportez des modifications aux paramètres de propriété concernant des transactions. Points de terminaison des propriétés 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 CMS Hub Pro ou Entreprise, ou Marketing Hub Pro ou Entreprise
conversations.read Affichez des détails concernant les fils dans la boîte de réception des conversations. API de boîte de réception des conversations et de messages Tout compte
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 CMS Hub Pro ou Entreprise, ou Marketing Hub 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

Tout compte 

Remarque : Seuls les comptes Pro et Entreprise peuvent utiliser ce domaine pour l'API des produits. 

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 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 CMS Hub Pro ou Entreprise, ou Marketing Hub 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 des engagements par e-mail. Consultez la vue d'ensemble des engagements pour plus de détails.
Sales Hub Gratuit, Starter, Pro ou Entreprise
settings.user.read Récupérez les utilisateurs et les rôles d'utilisateur à partir d'un compte HubSpot.  API de provisionnement des utilisateurs

Tous les comptes

Remarque : Seuls les comptes Entreprise peuvent utiliser ce domaine pour récupérer les rôles d'utilisateur. 

settings.user.teams.read Récupérez des équipes à partir d'un compte HubSpot.  API de provisionnement des utilisateurs

Pro ou Entreprise

social Comprend la boîte de réception des réseaux sociaux. API Réseaux sociaux Marketing Hub Pro ou Entreprise
tickets Comprend l'accès aux tickets. Points de terminaison des tickets Service Hub 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 Marketing Hub Pro ou Entreprise avec module complémentaire E-mails transactionnels

Documents associés