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

Connectez-vous à Notion, puis allez dans Paramètres (Settings) et dans la section Mes connexions (Connections), cliquez sur Développer puis Gérer mes intégrations. Vous pouvez aussi accéder directement via notion.so/my-integrations.

Étape 2 : créer une nouvelle intégration

Cliquez sur Nouvelle intégration et renseignez :

Un nom descriptif, par exemple Connecteur-ERP-Production ou Portail-Client-Lecture
Le workspace associé : l’intégration est liée à un seul workspace
Le logo (optionnel, mais utile pour identifier l’intégration dans les menus de partage)

Étape 3 : configurer les capacités

Dans la section Capacités (Capabilities), sélectionnez uniquement les permissions nécessaires :

Contenu :

Lire le contenu — lire les pages et bases de données (suffit pour un connecteur en lecture)
Mettre à jour le contenu — modifier des entrées existantes
Insérer du contenu — créer de nouvelles entrées

Utilisateurs :

Lire les informations utilisateurs sans adresse email — 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

Après validation, votre Internal Integration Token est affiché dans la section Secrets. Copiez-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 Partager (Share) en haut à droite, puis dans la section Inviter, 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.

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.

Pour aller plus loin

Approfondir votre réflexion

Retour : Expert API Notion

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

Notre stack technique

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