Guide de démarrage rapide pour OAuth

Avant de commencer

Avant de commencer à utiliser OAuth avec HubSpot, vous devrez disposer :

* Vous devez être un super administrateur pour installer une application dans un compte HubSpot.


Fonctionnement

HubSpot prend en charge le type d'octroi du code d'autorisation OAuth 2.0, qui peut être divisé en quatre étapes basiques :

  1. Votre application ouvre une fenêtre de navigateur pour renvoyer l'utilisateur au serveur OAuth 2.0 de HubSpot.
  2. L'utilisateur examine les autorisations demandées et accorde l'accès à l'application.
  3. L'utilisateur est redirigé vers l'application avec un code d'autorisation dans la chaîne de requête.
  4. L'application envoie une demande au serveur OAuth 2.0 pour échanger le code d'autorisation contre un jeton d'accès.
 

Dans ce guide

Remarque : Les exemples de code dans ce guide sont écrits en JavaScript (Node.js).

 

Application de démarrage rapide

Si vous utilisez pour la première fois l'authentification OAuth avec les API de HubSpot, nous vous recommandons vivement de consulter l'application de démarrage rapide d'OAuth 2.0, rédigée en Node.js. Cette application est conçue pour vous aider à bien démarrer avec OAuth 2.0, en vous en montrant toutes les étapes décrites ci-dessous dans Obtenir des jetons OAuth 2.0

Obtenir des jetons OAuth 2.0

Étape 1 : Créer l'URL d'autorisation et rediriger l'utilisateur vers le serveur OAuth 2.0 de HubSpot

Lorsque vous envoyez un utilisateur au serveur OAuth 2.0 de HubSpot, la première étape consiste à créer l'URL d'autorisation. Cela identifiera votre application et définira les ressources (périmètres d’accès) demandées au nom de l'utilisateur. Les paramètres de requête que vous pouvez transmettre dans une URL d'autorisation sont affichés ci-dessous. Pour plus d'informations sur cette étape, consultez la documentation de référence.

Paramètres de requête pour l'URL d'autorisation
Paramètre Obligatoire ? Description Exemple
client_id Oui L'ID de client identifie votre application. Trouvez-le sur la page des paramètres de votre application.

7fff1e36-2d40-4ae1-bbb1-5266d59564fb

scope Oui Les périmètres d’accès demandés par votre application, séparés par des espaces en format URL-encoded.

contacts%20social

redirect_uri Oui L'URL vers laquelle l'utilisateur sera redirigé après avoir autorisé votre application pour les périmètres d’accès demandés. Pour les applications de production, https est obligatoire.

https://www.exemple.com/auth-callback

optional_scope Non Les périmètres d’accès qui sont facultatifs pour votre application seront abandonnées si le portail HubSpot sélectionné n'a pas accès à ces produits.

automation

Une fois votre URL créée, commencez le processus OAuth 2.0 en y redirigeant l'utilisateur.

Exemples

Utilisation d'une redirection côté serveur :

// Build the auth URL const authUrl = 'https://app.hubspot.com/oauth/authorize' + `?client_id=${encodeURIComponent(CLIENT_ID)}` + `&scope=${encodeURIComponent(SCOPES)}` + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`; // Redirect the user return res.redirect(authUrl);

Utilisation d'un lien HTML :

<a href="https://app.hubspot.com/oauth/authorize?scope=contacts%20social&redirect_uri=https://www.example.com/auth-callback&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">Install</a>

Étape 2 : Demande de consentement de l'utilisateur par HubSpot

HubSpot affiche une fenêtre de consentement à l'utilisateur montrant le nom de votre application et une brève description des services d'API de HubSpot auxquels elle demande l'accès. L'utilisateur peut ensuite accorder l'accès à votre application.

oauth_2_grant_prompt

Remarque : L'utilisateur installant l'application doit avoir accès à tous les périmètres d’accès demandés. Autrement, l'installation échouera et il sera dirigé vers une page d'erreur. Si cette page d'erreur s'affiche, l'utilisateur devra demander à un super administrateur d'installer l'application.

Votre application n'exécute aucune action à cette étape. Une fois l'accès octroyé, le serveur OAuth 2.0 de HubSpot enverra une requête à l'URI de rappel (callback) définie dans l'URL d'autorisation.

Étape 3 : Traitement de la réponse du serveur OAuth 2.0

Lorsque l'utilisateur a répondu à la demande de consentement de l'étape 2, le serveur OAuth 2.0 envoie une requête GET à l'URI de redirection indiquée dans votre URL d'authentification. S'il n'y a aucun problème et que l'utilisateur a approuvé la demande d'accès, la requête à l'URI de redirection aura un retour avec le paramètre de requête code joint. Si l'utilisateur n'autorise pas l'accès, aucune requête ne sera envoyée.

Exemple :
app.get('/oauth-callback', async (req, res) => { if (req.query.code) { // Handle the received code } });

Étape 4 : Echange du code d'autorisation contre des jetons

Une fois que votre application reçoit un code d'autorisation de la part du serveur OAuth 2.0, elle peut échanger ce code contre un jeton d’accès et un jeton d'actualisation en envoyant une demande POST en format form-urlencoded à  https://api.hubapi.com/oauth/v1/token  avec les valeurs affichées ci-dessous. Pour plus d'informations sur cette étape, consultez la documentation de référence.

Paramètre Description Exemple
grant_type Doit être authorization_code authorization_code
client_id ID de client de votre application 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret Secret de client de votre application 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri URI de redirection lorsque l'utilisateur autorise votre application https://www.exemple.com/auth-callback
code Le code d'autorisation reçu de la part du serveur OAuth 2.0 5771f587-2fe7-40e8-8784-042fb4bc2c31
Exemple :
const formData = { grant_type: 'authorization_code', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, code: req.query.code }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

Le corps de la réponse du jeton sera composé de données JSON comme suit :

{"refresh_token":"6f18f21e-a743-4509-b7fd-1a5e632fffa1","access_token":"CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I","expires_in":21600}

Remarque :Le jeton d'accès expirera après le nombre de secondes indiqué dans le champ expires_in de la réponse (six heures). Pour plus d'informations sur la création d'un nouveau jeton d'accès, consultez Actualiser des jetons OAuth 2.0.

Utilisation des jetons OAuth 2.0

Une fois le flux de code d'autorisation terminé, votre application est autorisée à faire des demandes au nom de l'utilisateur. Pour cela, fournissez le jeton en tant que jeton Bearer dans l'en-tête HTTP Authorization. Des détails spécifiques sont disponibles dans la documentation de référence.

Exemple :
request.get('https://api.hubapi.com/contacts/v1/lists/all/contacts/all?count=1', { headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );

Actualisation des jetons OAuth 2.0

Les jetons d'accès OAuth expirent régulièrement. Ainsi, s'ils sont corrompus, les pirates informatiques n'y auront accès que pour une courte durée. Le cycle de vie du jeton (six heures par défaut) est indiqué dans le champ expires_in lorsqu'un code d'autorisation est échangé contre un jeton d'accès.

Votre application peut échanger le jeton d'actualisation reçu contre un nouveau jeton d'accès en envoyant une requête POST en format form-urlencoded à https://api.hubapi.com/oauth/v1/token avec les valeurs ci-dessous. Pour plus d'informations sur cette étape, consultez la documentation de référence.

Paramètre Description Exemple
grant_type Doit être refresh_token refresh_token
client_id ID de client de votre application 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret Secret de client de votre application 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri URI de redirection lorsque l'utilisateur autorise votre application https://www.exemple.com/auth-callback
refresh_token Le jeton d'actualisation reçu lorsque l'utilisateur autorise votre application b9443019-30fe-4df1-a67e-3d75cbd0f726
Exemple :
const formData = { grant_type: 'refresh_token', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, refresh_token: REFRESH_TOKEN }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

Le corps de la réponse du jeton sera composé de données JSON comme suit :

// Sample response { "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1", "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I", "expires_in": 21600 }

Le nouveau jeton d'accès peut ensuite être utilisé pour effectuer des appels au nom de l'utilisateur. Lorsque le nouveau jeton expire, vous pouvez suivre les mêmes étapes pour en récupérer un nouveau.