Intégration Notion / GUIDE TECHNIQUE
Créer vos identifiants API Notion : Integration Token et OAuth 2.0
Avant de connecter Notion à votre logiciel sur mesure, il faut créer une intégration interne avec les bonnes capacités et la partager explicitement avec vos bases. 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 Notion
Avant de connecter Notion à 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
Intégration interne (Internal Integration Token) pour les connecteurs côté serveur sur un seul workspace, OAuth 2.0 pour les applications multi-workspaces. Le choix dépend de qui exécute les requêtes.
Créer l'intégration en 5 minutes
Accès aux paramètres des intégrations Notion, création de l'intégration avec un nom descriptif, sélection des capacités au strict nécessaire. Le token est disponible immédiatement après création : à copier et stocker en sécurité.
Partager les bases et sécuriser le token
Partage explicite des pages et bases Notion avec l'intégration via le menu Share de chaque page. Stockage du token en variable d'environnement, jamais dans le code source.
Étape 1 : Choisir le bon type d’accès
Notion propose deux méthodes d’accès à son API. Le bon choix dépend de votre cas d’usage : une intégration interne pour un connecteur côté serveur sur votre propre workspace, ou OAuth 2.0 si l’application doit accéder à plusieurs workspaces Notion distincts.
Intégration interne (recommandée)
Une intégration interne est liée à un workspace Notion spécifique. Elle génère un Integration Token avec des capacités configurables (lecture, écriture, modification du contenu, lecture des informations utilisateurs). C’est l’option la plus simple pour un connecteur côté serveur, une synchronisation ou un portail client. Elle ne nécessite pas de flux OAuth.
OAuth 2.0
OAuth 2.0 est destiné aux applications qui doivent accéder à plusieurs workspaces Notion distincts. La mise en place est plus complexe (flux d’autorisation, gestion des refresh tokens, publication sur la galerie d’intégrations Notion) mais devient nécessaire si chaque client final doit autoriser l’accès à son propre workspace.
Étape 2 : Créer une intégration interne
Étape 1 : accéder aux paramètres des intégrations
Le terme “integrations” correspond à la terminologie anglaises de Notion, si vous avez l’interface en français tous les labels seront renommé par “connexions”.
Connectez-vous à Notion, puis allez dans Paramètres et dans la section Connexions, cliquez sur Développer ou gérer mes connexions.
Vous pouvez aussi accéder directement via le lien https://www.notion.so/profile/integrations/internal.
Étape 2 : créer une nouvelle intégration
Cliquez sur Créer une nouvelle connexion
Et renseignez :
- Un nom de connexion descriptif, par exemple
Connecteur-ERP-ProductionouPortail-Client-Lecture - Le logo (optionnel, mais utile pour identifier l’intégration dans les menus de partage)
- L’espace de travail (workspace) associé : l’intégration est liée à un seul workspace
Étape 3 : configurer les capacités
Une popup de confirmation vous indiquera “Connexion créée avec succès”, cliquez ensuite sur le bouton Configurer les paramètres de la connexion.
Dans la section Autorisations, sélectionnez uniquement les permissions nécessaires :
Contenu :
Consulter du contenu— lire les pages et bases de données (suffit pour un connecteur en lecture)Modifier du contenu— modifier des entrées existantesInsérer du contenu— créer de nouvelles entrées
Utilisateurs :
Consulter les informations des utilisateurs (hors adresses e‑mail).— accéder aux membres du workspace (rarement nécessaire pour un connecteur métier)
Le principe du moindre privilège reste essentiel : un connecteur en lecture seule n’a pas besoin des capacités d’écriture.
Étape 4 : copier et stocker le token
Vous trouverez le token de votre connexion/intégration interne dans cette même page de configuration, sous “Jeton d’accès d’installation”.
Cliquez sur Afficher et Copier.
Sauvegarder le immédiatement dans un gestionnaire de secrets ou de mots de passe.
Contrairement à certains outils, Notion affiche ce token à tout moment dans les paramètres de l’intégration, mais il est recommandé de le stocker dès la création pour ne pas en dépendre.
Étape 3 : Partager les bases avec l’intégration
C’est l’étape spécifique à Notion. Contrairement à la plupart des APIs, Notion n’expose pas automatiquement tout le contenu du workspace à une intégration. Chaque page ou base de données doit être explicitement partagée avec l’intégration.
Comment partager une base avec l’intégration
Ouvrez la base de données ou la page Notion concernée, cliquez sur le bouton … en haut à droite, puis dans la section Connexions, recherchez le nom de votre intégration et sélectionnez-la.
Les pages enfants héritent automatiquement du partage de leur parent : si vous partagez une page parente, toutes ses sous-pages et bases imbriquées deviennent accessibles à l’intégration.
Si l’API retourne une erreur 404 sur une base ou une page, c’est presque toujours parce que l’intégration n’a pas été partagée avec cette page. Vérifiez le partage avant de chercher une cause technique.
Vous pouvez retrouver toutes les pages et bases de données lié à votre integration token depuis sa page de configuration dans l’onglet Accès au contenu
Références
Étape 3 : Sécurité
Sécuriser et transmettre votre token
Un token Notion 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 !
C'est une contrainte de sécurité propre à Notion : une intégration n'accède qu'aux pages et bases qui lui ont été explicitement partagées. Si une base n'est pas partagée avec l'intégration, l'API retourne une erreur 404. Cette approche granulaire évite qu'une fuite de token expose l'intégralité du workspace.
Oui, chaque intégration créée dans les paramètres du workspace génère son propre token. Créer une intégration 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 Integration Tokens Notion n'ont pas de date d'expiration. 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évocation se fait directement depuis les paramètres de l'intégration dans Notion.
Le terme intégration publique ou connexion publique fait référence au type d'accès OAuth 2.0. Chaque utilisateur doit suivre le flux d'autorisation individuellement pour accorder l'accès. Ce type de connexion est utile dans un cadre multi-workspace.
Pour aller plus loin
Approfondir votre réflexion
Portail client, tableau de bord, synchronisation : découvrez tous les cas d'usages que nous pouvons développer avec l'API Notion.
Symfony, Vue.js, Clever Cloud : les technologies que nous utilisons pour développer des connecteurs robustes et maintenables.