Dernière modification : 12 septembre 2025
‘Travailler avec OAuth | Guide de démarrage rapide pour OAuth’;
“Découvrez comment configurer OAuth pour votre application à l’aide de ce guide de démarrage rapide et de cet exemple d’application Node.js.”;
Avant de commencer
Avant de commencer à utiliser OAuth avec HubSpot, vous devrez disposer :
Fonctionnement
HubSpot prend en charge le type d’octroi du code d’autorisation OAuth 2.0, qui peut être divisé en quatre étapes basiques :
- Votre application ouvre une fenêtre de navigateur pour renvoyer l’utilisateur au serveur OAuth 2.0 de HubSpot.
- L’utilisateur examine les autorisations demandées et accorde l’accès à l’application.
- L’utilisateur est redirigé vers l’application avec un code d’autorisation dans la chaîne de requête.
- 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
Application de démarrage rapide
Si vous utilisez pour la première fois l’authentification OAuth avec les API de HubSpot, il est fortement recommandé 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 la section Obtenir des jetons OAuth ci-dessous.
Obtenir des jetons OAuth
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 dans le tableau ci-dessous. Pour plus d’informations sur cette étape, consultez la documentation de référence.
Les champs marqués par * sont
obligatoires.
| Paramètre | Description | Exemple |
|---|
client_id* | L’ID de client identifie votre application. Trouvez-le sur la page des paramètres de votre application. | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
scope* | Les périmètres d’accès demandés par votre application, séparés par des espaces en format URL-encoded (%20). | oauth%20crm.objects.contacts.read |
redirect_uri* | 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.example.com/auth-callback |
optional_scope | 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 |
state | Une valeur de chaîne unique pouvant être utilisée pour maintenir l’état de l’utilisateur lorsqu’il est redirigé vers votre application. | WeHH_yy2irpl8UYAvv-my |
Une fois votre URL créée, commencez le processus de connexion OAuth 2.0 en y redirigeant l’utilisateur.
Les blocs de code ci-dessous fournissent des exemples d’utilisation de différents types de redirection :
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)}` +
`&state=${encodeURIComponent(STATE)}`;
// Redirect the user
return res.redirect(authUrl);
<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&state=xxxxxxxx"
>Install</a
>
userA.integration.com et userB.integration.com). Pour ce faire, utilisez le paramètre state pour encoder plus d’informations sur le statut de l’utilisateur :
1. Générez et stockez une valeur nonce pour le paramètre de statut.
2. Stockez le statut de l’utilisateur dans une banque de données locale en utilisant le nonce comme clé.
3. Incluez la valeur nonce comme paramètre de statut dans l’URL d’autorisation.
4. Lorsque l’utilisateur s’authentifie et est redirigé vers l’URL de redirection, validez le paramètre de statut et utilisez-le comme clé pour récupérer le statut de l’utilisateur stocké.
5. À partir de là, redirigez l’utilisateur au besoin (par exemple, rediriger à nouveau vers une URL spécifique à l’utilisateur).
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.
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.
3. Gérer la réponse du serveur OAuth
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
}
});
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 correspondre à 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.example.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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
Utilisation des jetons OAuth
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
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 est indiqué en secondes 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 correspondre à 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.example.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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
Articles connexes
Méthodes d’authentification sur HubSpot
Travailler avec OAuth
Gérer les jetons
