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. 
  • Les utilisateurs qui installent des applications dans leur compte HubSpot doivent être un super administrateur ou disposer d'autorisations d' accès aux marketplace des applications.
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. 
  • Les jetons d'accès reflètent les périmètres d'accès demandés à l'application et pas les autorisations ou les limites de ce qu'un utilisateur peut faire dans son compte HubSpot. Par exemple, si un utilisateur dispose des autorisations pour afficher uniquement les contacts détenus, mais autorise une demande pour le périmètre d'accès crm.objects.contacts.read, le jeton d'accès résultant peut afficher tous les contacts du compte et pas seulement ceux détenus par l'utilisateur autorisant. 

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 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 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
cms.domains.read Les intégrateurs peuvent répertorier les domaines CMS dans le compte d'un client.  API du CMS Tout compte
cms.domains.write Les intégrateurs peuvent créer, mettre à jour et supprimer des domaines personnalisés CMS.  API du CMS Tout compte
cms.functions.read Les intégrateurs peuvent afficher toutes les fonctions sans serveur CMS, tous les secrets associés et les résultats d'exécution de fonction.  API du CMS CMS Hub Entreprise
cms.functions.write Les intégrateurs peuvent écrire des fonctions sans serveur CMS et des secrets. API du CMS CMS Hub Entreprise
cms.knowledge_base.articles.read Pour afficher les détails sur les articles de la base de connaissances. API du CMS Service Hub Pro ou Entreprise 

cms.knowledge_base.articles.write

 Pour mettre à jour des articles de la base de connaissances.  API du CMS Service Hub Pro ou Entreprise 
cms.knowledge_base.articles.publish Pour mettre à jour et publier des articles de la base de connaissances. API du CMS Service Hub Pro ou Entreprise 
cms.knowledge_base.settings.read Pour afficher les paramètres généraux et de la base de connaissances, tels que l'URL du domaine ou de la racine. API du CMS Service Hub Pro ou Entreprise 
cms.knowledge_base.settings.write Pour mettre à jour les paramètres généraux et de la base de connaissances. Cela inclut l'accès en écriture aux articles de la base de connaissances. API du CMS Service Hub Pro ou Entreprise 
cms.performance.read Les intégrateurs peuvent afficher les données sur les performance CMS pour tous vos sites. API du CMS Tout compte
crm.lists.read Pour afficher les détails concernant des listes de contacts. Points de terminaison de liste Tout compte
crm.lists.write Pour créer, supprimer ou apporter des modifications à des listes de contacts. Points de terminaison de liste Tout compte
crm.objects.companies.read Pour afficher les propriétés et d'autres détails sur les entreprises. Points de terminaison d'entreprises Tout compte
crm.objects.companies.write Pour afficher les propriétés et créer, supprimer ou apporter des modifications aux entreprises. Points de terminaison d'entreprises Tout compte
crm.objects.contacts.read Pour afficher les propriétés et d'autres détails sur les contacts. Points de terminaison des contacts Tout compte
crm.objects.contacts.write Pour afficher les propriétés et créer, supprimer ou apporter des modifications aux contacts. Points de terminaison des contacts Tout compte
crm.objects.custom.read Pour afficher les détails des objets personnalisés dans le CRM. Points de terminaison d'objets personnalisés Tout forfait Enterprise
crm.objects.custom.write Pour créer, supprimer ou apporter des modifications à des objets personnalisés dans le CRM.  Points de terminaison d'objets personnalisés Tout forfait Enterprise
crm.objects.deals.read Pour afficher les propriétés et d'autres détails sur les transactions. Points de terminaison des transactions Tout compte
crm.objects.deals.write Pour afficher les propriétés et créer, supprimer ou apporter des modifications aux transactions. Points de terminaison des transactions Tout compte
crm.objects.feedback_submission.read Pour afficher les détails des soumissions pour n'importe laquelle de vos enquêtes de feedback. Points de terminaison d'enquêtes de feedback Service Hub Pro ou Entreprise
crm.objects.goals.read Pour afficher tous les types d'objectifs  Points de terminaison d'objectifs Sales Hub Starter, Pro ou Entreprise
crm.objects.line_items.read Pour afficher les propriétés et d'autres détails sur les lignes de produits. Points de terminaison de lignes de produits Tout compte
crm.objects.line_items.write Pour créer, supprimer ou apporter des modifications à des lignes de produits.  Points de terminaison de lignes de produits Tout compte
crm.objects.marketing_events.read Pour afficher les détails des événements marketing.  Points de terminaison d'événements marketing Tout compte
crm.objects.marketing_events.write Pour créer, supprimer ou apporter des modifications à des événements marketing.  Points de terminaison d'événements marketing Tout compte
crm.objects.owners.read Pour afficher des détails concernant les utilisateurs attribués à une fiche d'informations du CRM. Points de terminaison des propriétaires Tout compte
crm.objects.quotes.read Pour afficher les propriétés et d'autres détails sur les devis et modèles de devis. Points de terminaison de devis Tout compte
crm.objects.quotes.write Pour créer, supprimer ou apporter des modifications à des devis. Points de terminaison de devis Tout compte
crm.schemas.companies.read Pour afficher 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 Pour créer, supprimer ou apporter des modifications aux paramètres de propriété concernant des entreprises. Points de terminaison des propriétés Tout compte
crm.schemas.contacts.read Pour afficher 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 Pour créer, supprimer ou apporter des modifications aux paramètres de propriété concernant des contacts. Points de terminaison des propriétés Tout compte
crm.schemas.custom.read Pour afficherr les détails des définitions d'objets personnalisés dans le CRM. Points de terminaison d'objets personnalisés Tout forfait Enterprise
crm.schemas.deals.read Pour afficher 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 Pour créer, supprimer ou apporter des modifications aux paramètres de propriété concernant des transactions. Points de terminaison des propriétés Tout compte
crm.schemas.line_items.read Pour afficher les détails des lignes de produits. Points de terminaison de lignes de produits Tout compte
crm.schemas.quotes.read Pour afficher les détails sur les devis et modèles de devis. Points de terminaison de devis Tout compte
settings.billing.write Pour modifier les paramètres de facturation de votre compte. Cela inclut la gestion et l'attribution de licences payantes pour les utilisateurs. Points de terminaison des paramètres Tout compte
settings.currencies.read Pour lire un des taux de change existants avec la devise d'entreprise actuellement associée à votre portail.  Points de terminaison des informations sur le compte Tout compte
settings.currencies.write Pour créer, mettre à jour et supprimer les taux de change ainsi que la mise à jour de la devise de l'entreprise associée à votre portail.  Points de terminaison des informations sur le compte Tout compte
settings.users.read Pour afficher les détails concernant les utilisateurs du compte et leurs autorisations. Points de terminaison de provisionnement des utilisateurs Tout compte
settings.users.write Pour gérer les utilisateurs et les autorisations des utilisateurs sur votre compte HubSpot. Cela inclut la création de nouveaux utilisateurs, l'attribution d'autorisations et de rôles et la suppression d'utilisateurs existants.  Points de terminaison de provisionnement des utilisateurs Tout compte
settings.users.teams.read Pour consulter les détails des équipes du compte.  Points de terminaison de provisionnement des utilisateurs Tout compte
settings.users.team.write Pour attribuer des utilisateurs à des équipes sur votre compte HubSpot.  Points de terminaison de provisionnement des utilisateurs Tout compte
account-info.security.read Comprend l'accès aux journaux d'activité du compte et à d'autres informations sur la sécurité du compte.  API de l'activité du compte Tout compte
accounting Permet à HubSpot et à l'intégration de comptabilité de partager des informations sur les factures, les produits et les contacts. API pour les extensions comptables Tout compte
actions Pour ajouter des formulaires aux pages du contact qui effectuent des actions personnalisées. API des extensions CRM Tout compte
analytics.behavioral_events.send Inclut l'accès à l'envoi d'événements comportementaux personnalisés.  API Analytics Marketing Hub Entreprise
automation Comprend les workflows. API Automatisation (points de terminaison des workflows) Marketing Hub Pro ou Entreprise
behavioral_events.event_definitions.read_write Pour créer, lire, mettre à jour ou supprimer des événements comportementaux. Cela inclut les propriétés des événements comportementaux.  API Analytics Marketing Hub Entreprise
business_units.view.read Pour afficher les données sur l'unités commerciale, y compris les informations sur le logo. API d'unités commerciales Module complémentaire Unités commerciales
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
communication_preferences.read Pour afficher les détails des préférences d'abonnement de vos contacts.  API des préférences d'abonnement Tout compte
communication_preferences.read_write Pour abonner/désabonner des contacts de vos types d'abonnement. Cela n'abonnera pas les contacts qui se sont désabonnés.  API des préférences d'abonnement Tout compte
communication_preferences.write Pour abonner/désabonner des contacts de vos types d'abonnement. Cela n'abonnera pas les contacts qui se sont désabonnés.  API des préférences d'abonnement Tout compte
content Comprend les sites, les pages de destination, 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
conversations.write Pour envoyer des messages dans les conversations, créer et mettre à jour des fils de discussion. API de boîte de réception des conversations et de messages Tout compte
crm.export Pour exporter les fiches d'informations de votre CRM pour tous les types de données CRM. API d'exports CRM  Tout compte
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
ctas.read Permet l'accès en lecture des CTA. Aucune API publique disponible Marketing Hub ou CMS Hub Starter, 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.
external_integrations.forms.access Inclut la possibilité de renommer, supprimer et cloner des formulaires existants. Points de terminaison des formulaires

Tout compte
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
files.ui_hidden.read Pour afficher les détails ou télécharger des fichiers utilisateur, des pièces jointes ou des fichiers système à partir de l'ensemble des outils de HubSpot.  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 Site web
integration-sync Expose l'API de synchronisation, qui permet la synchronisation de la plupart des objets de CRM. API Bridge e-commerce Tout compte
media_bridge.read Permet d'accéder aux événements et aux objets depuis la passerelle multimédia. API de passerelle multimédia Tout compte
media_bridge.write Permet d'accéder à la création et à la mise à jour d'événements et d'objets à partir de la passerelle multimédia. API de passerelle multimédia Tout compte
oauth Le domaine de base nécessaire pour OAuth. Ce périmètre d'accès est ajouté par défaut à toutes les applications.   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.		 Tout compte
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 Tout compte
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

Méthodes d'authentification sur HubSpot

Guide de démarrage rapide pour OAuth

Gestion des jetons