Créer vos identifiants API HubSpot : Private App Token et OAuth 2.0

Avant de connecter HubSpot à votre logiciel sur mesure, il faut créer une Private App avec les bons scopes et les bonnes restrictions. Ce guide vous explique la procédure complète, du choix du type d'accès à la transmission sécurisée du token.

LES ÉTAPES

3 étapes pour créer et sécuriser vos identifiants API HubSpot

Avant de connecter HubSpot à votre logiciel sur mesure, il faut générer les bons identifiants avec les bonnes permissions. Voici les étapes à suivre.

Choisir le bon type d'accès

Private App Token pour les connecteurs côté serveur, OAuth 2.0 pour les applications multi-comptes HubSpot. Le choix dépend de qui exécute les requêtes.

Créer la Private App en 5 minutes

Accès aux paramètres d'intégration HubSpot, création de l'application avec un nom descriptif, sélection des scopes au strict nécessaire. Le token n'est affiché qu'une seule fois après création : à copier immédiatement.

Sécuriser et transmettre le token

Stockage en variable d'environnement, jamais dans le code source. Transmission via gestionnaire de mots de passe partagé, jamais par email ou Slack en clair.

Étape 1 : Choisir le bon type d’accès

HubSpot propose deux méthodes d’authentification. Le bon choix dépend de votre cas d’usage : un connecteur côté serveur dans la plupart des cas, ou une application multi-comptes si chaque utilisateur doit se connecter avec son propre compte HubSpot.

Private App Token (recommandé)

Le Private App Token est lié à un compte HubSpot spécifique et utilise des scopes granulaires par type d’objet CRM et par opération (lecture, écriture). C’est l’option recommandée pour un connecteur côté serveur, une synchronisation ERP ou un portail client. Il est plus rapide à créer et à révoquer qu’un flux OAuth. Même si HubSpot le considère aujourd’hui comme legacy, il reste le plus simple à mettre en place et demeure le moyen le plus adapté à certaines situations spécifiques.

OAuth 2.0

OAuth 2.0 est destiné aux applications qui doivent agir au nom de plusieurs comptes HubSpot distincts (agences, revendeurs, ISV). La mise en place est plus complexe : plus de code, flux d’autorisation, gestion des refresh tokens. Mais elle devient nécessaire si chaque client final doit autoriser l’accès à son propre portail HubSpot.

Étape 2 : Créer une Private App

La Private App est la méthode standard pour connecter HubSpot à un système externe. Voici la procédure complète.

Étape 1 : accéder aux paramètres d’intégration

Connectez-vous à votre portail HubSpot, puis allez dans le menu principal de gauche dans Développement. Dans le sous-menu de gauche, naviguez jusqu’à Applications héritées.

Applications héritées dans les paramètres

Étape 2 : créer l’application

Cliquez sur Créer une application héritée et renseignez :

Type Privé
Un nom descriptif, par exemple Connecteur-ERP-Production ou Portail-Client-Lecture
Un logo représentatif pour faciliter la reconnaissance visuelle dans l’interface
Une description facultative (utile pour l’audit si plusieurs apps coexistent)

Un nom clair facilite la révocation ciblée si une fuite est détectée plus tard.

Applications héritées dans les paramètres

Étape 3 : sélectionner les scopes

Dans l’onglet Domaines ou Scopes, choisissez uniquement les permissions nécessaires au connecteur. Les scopes CRM les plus courants sont :

crm.objects.contacts.read et .write pour les contacts
crm.objects.companies.read et .write pour les entreprises
crm.objects.deals.read et .write pour les affaires
crm.objects.tickets.read et .write pour les tickets
crm.schemas.contacts.read pour lire les propriétés personnalisées

Le principe du moindre privilège reste essentiel : moins une app a de scopes, plus elle est sûre en cas de fuite. N’activez pas crm.objects.deals.write si votre connecteur ne fait que lire les deals.

Domaines d'une application héritée

Étape 4 : créer l’application et copier le token

Cliquez sur Créer une application. HubSpot affiche le token une seule fois après la création. Copiez-le immédiatement dans un gestionnaire de secrets ou de mots de passe : il ne sera plus visible ensuite. Si vous le perdez, vous devrez en générer un nouveau (l’ancien est automatiquement révoqué).

Domaines d'une application héritée

Étape 3 : Sécuriser et transmettre le token

Stockage

Ne jamais stocker le token dans le code source, même dans un fichier .env versionné. Utilisez :

Une variable d’environnement sur le serveur (.env local non versionné, secrets CI/CD)
Un gestionnaire de secrets (Vault, AWS Secrets Manager, Doppler…)

Transmission au prestataire

Partagez le token via un gestionnaire de mots de passe partagé (Bitwarden, 1Password, Dashlane). Jamais par email, Slack ou ticket de support en clair. Si vous avez un doute sur une transmission non sécurisée, révoquez le token immédiatement et régénérez-en un nouveau.

Références

Étape 3 : Sécurité

Sécuriser et transmettre votre token

Un token HubSpot donne accès à vos données métier. Quelques règles simples évitent les fuites accidentelles et permettent une révocation rapide en cas de problème.

Ne jamais committer le token

Un token dans un dépôt git (même privé) est une fuite de sécurité. Il doit toujours passer par une variable d'environnement dans votre .env local, jamais dans le code source.

Variable d'environnement côté serveur

Sur Clever Cloud (notre infrastructure d'hébergement), les variables d'environnement sont configurées depuis la console et injectées au démarrage de l'application. Elles ne sont jamais exposées côté client.

Comment nous le transmettre

Utilisez un gestionnaire de mots de passe partagé (Bitwarden, 1Password) ou notre formulaire de partage sécurisé. Jamais par email ou par message Slack en clair.

FAQ

Les réponses à vos questions

Et si vous ne trouvez pas ce que vous cherchez, nous serons ravis de vous répondre en direct lors d'un rendez-vous entre humains !

Oui, HubSpot ne limite pas le nombre de Private Apps par compte. Créer une app par environnement (développement, staging, production) et par connecteur permet de révoquer un accès précis sans impacter les autres systèmes.

Les Private App Tokens HubSpot n'ont pas de date d'expiration par défaut. Il est recommandé de les révoquer et régénérer régulièrement, ou immédiatement en cas de doute sur une fuite. La régénération produit un nouveau token sans modifier les scopes configurés.

Non. HubSpot a définitivement supprimé les API keys legacy en novembre 2022. Tout nouveau connecteur doit utiliser un Private App Token ou OAuth 2.0. Si vous avez un ancien connecteur basé sur les API keys, il doit être migré vers les Private Apps pour continuer à fonctionner.

Pour aller plus loin

Approfondir votre réflexion

Retour : Expert API HubSpot

Portail client, tableau de bord, synchronisation : découvrez tous les cas d'usages que nous pouvons développer avec l'API HubSpot.

Notre stack technique

Symfony, Vue.js, Clever Cloud : les technologies que nous utilisons pour développer des connecteurs robustes et maintenables.