Dernière modification : 28 août 2025
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 de OAuth avec HubSpot, y compris une répartition du flux HubSpot-OAuth et des explications sur l’actualisation d’un jeton d’accès.

​
Configurer l’authentification OAuth

Pour configurer l’authentification OAuth pour votre application :
  • Tout d’abord, créez une application dans un compte de développeur HubSpot. Après avoir créé l’application, 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
  • 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. Vous pouvez définir l’URL d’autorisation comme étant destinée à un compte HubSpot spécifique en ajoutant l’ID du compte entre /oauth/ et /authorize, comme indiqué ci-dessous. Après avoir autorisé l’accès, ils seront redirigés vers votre application via un redirect_url, qui sera associé à un paramètre de requête de code. Vous utiliserez ce code et le secret client pour obtenir un access_token et un refresh_token depuis HubSpot.
    • Exemples d’URL d’autorisation
      • Tout compte : https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
      • Compte spécifique (ID 123456 : https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
    • Exemple d’URL de redirection : https://example.com/?code=xxxx
    • Exemple d’erreur : https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
  • Utilisez le access_token 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 de requêtes suivants sont obligatoires lors de la création d’une URL d’autorisation pour votre compte :
ParamètreDescriptionMode d’emploi
client_idUn ID qui sert d’identifiant unique pour votre application.Vous pouvez l’obtenir depuis la page des paramètres d’authentification de votre application (comme décrit ci-dessus).
redirect_uriL’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 pouvez être utilisé.) Vous devez également utiliser un domaine, car les adresses IP ne sont pas prises en charge.
scopeUn 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 la documentation de référence sur les domaines pour plus de détails sur les points de terminaison disponibles pour des domaines spécifiques.
Les paramètres suivants sont facultatifs :
ParamètreMode d’emploiDescription
optional_scopeUn ensemble d’autorisations séparées par des espaces pour votre application.Les domaines facultatifs seront automatiquement supprimés de la requête d’autorisation si l’utilisateur sélectionne un compte HubSpot qui n’a pas accès à cet outil (par exemple, pour autoriser un domaine Content Hub Entreprise dans un compte gratuit HubSpot). 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 la documentation de référence sur les domaines pour plus de détails.
stateSi 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 le redirect_uri.Une valeur de chaîne pouvant être utilisée pour maintenir l’état de l’utilisateur lorsqu’il est redirigé vers votre application.

​
Configurer des 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.
granular-scopes-selection
L’accès à des API ou points de terminaison spécifiques dépend du niveau de compte HubSpot. 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 HubSpot gratuits 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. La liste complète des domaines d’application est disponible ici.

​
Documents associés

Méthodes d’authentification sur HubSpot Guide de démarrage rapide pour OAuth Gestion des jetons