Pourquoi utiliser OAuth plutôt qu'une clé d'API pour brancher un assistant ?

Avec OAuth, c'est le client qui accorde l'accès à votre application, pour une liste de droits précise (les scopes), sans vous communiquer son mot de passe. Les jetons sont limités dans le temps et le client peut retirer l'accès.

Que faire quand le jeton de rafraîchissement ne marche plus ?

Chez HubSpot, la réponse d'erreur contient invalid_grant : jeton invalide, expiré ou révoqué. Chez Pipedrive, un jeton de rafraîchissement expiré oblige à refaire l'installation complète. Prévoyez une alerte et un parcours de reconnexion pour le client.

Où stocker les jetons OAuth d'un client ?

La RFC 6749 demande de garder les jetons confidentiels, au repos comme en transit, et de ne les transmettre que par TLS. En pratique : un coffre ou une base chiffrée, jamais dans le code, les journaux ou le navigateur.

Connecter une application à un CRM avec OAuth

Connecter une application à un CRM avec OAuth 2.0 revient à faire accorder l'accès par le client lui-même : il est renvoyé vers le CRM, accepte une liste de droits, et votre application reçoit un jeton d'accès de courte durée plus un jeton de rafraîchissement pour en obtenir d'autres. Vous ne voyez jamais son mot de passe. Cette page explique le principe, le déroulé, puis ce qui se passe après : stockage, expiration, révocation. Sources lues le 15/11/2026 : la RFC 6749 (le texte de référence d'OAuth 2.0), la documentation développeur de HubSpot et celle de Pipedrive.

Le principe en quatre mots

Code d'autorisation : une valeur à usage unique, remise à votre application après l'accord du client. Elle ne donne rien par elle-même ; on l'échange contre des jetons. La RFC recommande qu'elle expire vite (10 minutes au maximum) et qu'elle ne serve qu'une fois (section 4.1.2). Pipedrive la fait expirer au bout de 5 minutes.
Jeton d'accès : la clé qui accompagne chaque appel à l'API. La RFC le décrit comme un identifiant qui représente un périmètre et une durée d'accès définis (section 1.4). HubSpot le dit « short-lived », avec la durée en secondes dans le champ expires_in (l'exemple de la page affiche 1800, soit 30 minutes) ; Pipedrive indique 60 minutes.
Jeton de rafraîchissement : sert uniquement à obtenir de nouveaux jetons d'accès. Il n'est envoyé qu'au serveur d'autorisation, jamais à l'API métier (section 1.5).
Scopes (périmètres) : la liste des droits demandés, par exemple lire les contacts ou écrire des activités. Le serveur peut accorder moins que demandé et doit alors le signaler (section 3.3).

Le pas à pas général

Enregistrer l'application chez l'éditeur du CRM. Vous obtenez un identifiant et un secret d'application, et vous déclarez l'adresse de retour (redirect_uri). La RFC demande de l'enregistrer à l'avance (section 3.1.2.2) : une adresse qui ne correspond pas est refusée.
Rediriger le client vers la page d'autorisation du CRM avec l'identifiant de l'application, les scopes, l'adresse de retour et une valeur state. Chez Pipedrive, c'est oauth.pipedrive.com/oauth/authorize.
Le client décide. Il voit l'application et les droits demandés. Pipedrive précise qu'il accepte ou refuse l'ensemble des scopes demandés.
Retour sur votre adresse avec un code (ou error=user_denied chez Pipedrive si le client refuse) et le state renvoyé à l'identique. Comparez ce state à celui que vous aviez envoyé : la RFC demande de protéger l'adresse de retour contre les attaques CSRF (section 10.12), typiquement par une valeur non devinable liée à la session de l'utilisateur.
Échanger le code côté serveur : un appel POST au point d'accès des jetons avec le code, l'adresse de retour et l'authentification de l'application. Pipedrive recommande l'authentification HTTP Basic ; envoyer l'identifiant et le secret dans le corps est possible mais déconseillé. Cet échange ne se fait jamais dans le navigateur, puisqu'il utilise le secret.
Enregistrer les jetons et la date d'expiration, puis appeler l'API avec l'en-tête Authorization: Bearer <jeton>.
Rafraîchir avant l'expiration : POST avec grant_type=refresh_token. HubSpot attend refresh_token, client_id et client_secret vers https://api.hubapi.com/oauth/v1/token.

Les scopes : demander le minimum

La RFC dit que le client doit demander le scope minimal nécessaire (section 10.3). Les deux CRM lus vont dans ce sens. Pipedrive recommande de ne demander que les scopes « absolutely necessary », et refuse les appels hors des scopes accordés. HubSpot permet de distinguer les scopes demandés (scopes) de scopes facultatifs (optional_scopes) dans l'adresse d'installation. Pour un assistant qui répond aux questions des commerciaux, la lecture suffit presque toujours ; l'écriture se demande seulement pour les actions que l'assistant fait vraiment. Le détail de ce raisonnement est dans les droits d'accès d'un assistant IA.

Stocker les jetons

La RFC est nette : les jetons d'accès et de rafraîchissement doivent rester confidentiels, en transit comme au stockage, et ne passer que par TLS (sections 10.3 et 10.4). Ce que cela donne pour un intégrateur :

un coffre de secrets ou une base chiffrée, un enregistrement par client et par application ;
jamais dans le code, un dépôt, un journal d'application ou une page web ;
prévoir de la place : Pipedrive recommande un champ d'au moins varchar(768) pour le jeton d'accès, dont la longueur peut varier ;
enregistrer aussi la date d'expiration et la date du dernier rafraîchissement réussi.

Expiration et rotation

Élément	HubSpot	Pipedrive
Code d'autorisation	non précisé sur la page lue	5 minutes
Jeton d'accès	court ; durée dans `expires_in`	60 minutes (à confronter à `expires_in`)
Jeton de rafraîchissement	durée non précisée sur la page lue	expire après 60 jours sans usage ; chaque usage remet 60 jours

La RFC recommande la rotation : un nouveau jeton de rafraîchissement à chaque usage, l'ancien invalidé, ce qui permet de détecter une compromission (section 10.4). Ce n'est pas ce que fait Pipedrive : sa réponse renvoie le même jeton de rafraîchissement, avec une fenêtre d'expiration prolongée. Lisez donc la réponse de chaque éditeur au lieu de supposer, et enregistrez le jeton renvoyé s'il change.

Un point d'organisation : un client dont l'assistant ne sert pas pendant plus de 60 jours peut perdre son accès Pipedrive. Un appel de rafraîchissement planifié, et une alerte s'il échoue, évitent la surprise.

Révoquer un accès

Chez HubSpot, DELETE /oauth/v1/refresh-tokens/{token} supprime le jeton de rafraîchissement. La page précise que les jetons d'accès déjà émis ne sont pas supprimés et que l'application n'est pas désinstallée de la session : ils s'éteignent à leur expiration. Pour Pipedrive, la page lue ne décrit ni la désinstallation ni la révocation ; consultez la documentation Marketplace avant de promettre un délai à un client. À la fin d'un contrat, prévoyez dans tous les cas deux gestes : supprimer vos copies des jetons, et demander au client de retirer l'application côté CRM.

Erreurs courantes

invalid_grant : code ou jeton de rafraîchissement invalide, expiré, révoqué, ou ne correspondant pas à l'adresse de retour (RFC 6749, section 5.2). Chez HubSpot, la description est « refresh token is invalid, expired or revoked ». Il faut refaire l'autorisation.
invalid_client : identifiant ou secret d'application faux, ou méthode d'authentification non acceptée.
invalid_scope : scope inconnu ou plus large que ce qui a été accordé.
Adresse de retour différente de celle enregistrée : le serveur ne redirige pas, ou refuse l'échange.
Code réutilisé ou expiré : la RFC demande de refuser la réutilisation d'un code ; l'échange doit suivre immédiatement le retour.
Appel hors scope : chez Pipedrive, l'API refuse les points d'accès que les scopes accordés ne couvrent pas.
Version d'API qui change : la page HubSpot annonce la dépréciation de la v1 de l'API OAuth le 16/02/2027 et renvoie à un guide de migration. Relisez la page avant de bâtir sur un point d'accès.

Après l'autorisation

Un jeton qui fonctionne ne règle pas la suite : volume d'appels, pannes, jetons périmés. Pour Pipedrive, voir l'intégration API Pipedrive ; pour HubSpot, le chatbot IA sur HubSpot ; pour choisir entre un accès direct et un serveur MCP, MCP ou API.