Comment obtenir une clé API Notion et trouver les identifiants nécessaires à vos requêtes

Une clé API Notion est le jeton que votre code envoie avec chaque requête à l’API Notion. En 2026, il en existe trois types : un jeton d’accès personnel qui agit en votre nom, un jeton de connexion interne pour les automatisations d’équipe, et OAuth pour les applications que d’autres personnes installent. Découvrez ci-dessous comment créer chacun d’eux, lui donner accès à vos pages, trouver les identifiants de page, de base de données et de source de données nécessaires à vos requêtes, et résoudre les erreurs que presque tout le monde rencontre au premier essai.

De quelle clé API Notion avez-vous besoin ?

La documentation de Notion destinée aux développeurs présente trois méthodes d’authentification. Elles se distinguent par les personnes dont le jeton reprend les autorisations, les données auxquelles il donne accès et les personnes autorisées à le créer.

Pour choisir rapidement :

• Un script, un notebook ou un outil que vous seul utilisez : un jeton d’accès personnel. Rien à partager, tout fonctionne en deux minutes.
• Une automatisation sur laquelle l’équipe compte : une connexion interne. Elle continue de fonctionner même si la personne qui l’a configurée s’en va, et n’a accès qu’aux pages que vous partagez avec elle.
• Une application que d’autres personnes installent : une connexion publique avec OAuth. Ne demandez jamais à vos utilisateurs de coller un jeton.
• Claude, ChatGPT, Cursor ou une autre application d’IA : généralement, aucune clé n’est nécessaire. Le serveur MCP hébergé par Notion vous connecte via OAuth ; notre guide MCP pour Notion explique la configuration.

Option 1 : créez un jeton d’accès personnel

Un jeton d’accès personnel (PAT) agit en votre nom, avec votre statut de membre de l’espace de travail et vos autorisations sur les pages. Le guide de démarrage rapide de l’API de Notion commence lui-même par un tel jeton, car il n’y a rien d’autre à configurer que le jeton.

1. Activez le mode développeur. Dans Notion, ouvrez les Paramètres, recherchez Mode développeur et activez-le. Ce réglage est local : vous devez l’activer séparément dans le navigateur et dans l’application de bureau. Il n’est pas disponible sur mobile.
2. Ouvrez la liste des jetons. Une section dédiée aux développeurs apparaît dans la barre latérale. Ouvrez Jetons d’accès personnels et cliquez sur Nouveau jeton. Voici le lien direct : notion.so/developers/tokens.
3. Nommez le jeton et définissez sa portée. Sélectionnez la fonctionnalité API Notion (ajoutez Workers uniquement si vous déployez des Notion Workers) et une durée de validité : 7, 30, 90 ou 180 jours, ou 1 an, la valeur par défaut. Si un sélecteur d’espace de travail apparaît, choisissez l’espace de travail : un jeton est rattaché à un seul espace de travail.
4. Cliquez sur Créer un jeton et copiez immédiatement sa valeur. Notion ne l’affiche qu’une seule fois, puis plus jamais, même aux administrateurs. Conservez-la dans un gestionnaire de mots de passe ou dans le gestionnaire de secrets de votre projet.

Les nouveaux jetons commencent par ntn_. Notion a remplacé le préfixe secret_ le 25 septembre 2024, et les anciens jetons continuent de fonctionner. Ne vérifiez toutefois pas le préfixe dans votre code : Notion indique que le format peut changer et demande aux développeurs de traiter les jetons comme des chaînes opaques.

Vous n’arrivez pas à créer un jeton ?

Les invités et les membres à accès restreint ne peuvent pas créer de PAT. Pour tous les autres utilisateurs, le forfait détermine qui peut en créer un donnant accès à l’API Notion :

Avec les forfaits Business et Enterprise, demandez à un propriétaire de l’espace de travail de l’autoriser dans Paramètres → Connexions. Si un administrateur rend ensuite la politique d’autorisation plus restrictive, les jetons dont vous disposez déjà cessent de fonctionner et renvoient unauthorized.

Ce à quoi un PAT peut accéder

Tout ce que vous pouvez ouvrir dans cet espace de travail : pages, bases de données, commentaires et fichiers. Il n’est pas nécessaire de partager les pages avec le jeton. C’est ce qui rend les PAT rapides à utiliser, mais aussi ce qui rend la divulgation d’un PAT coûteuse. La documentation de Notion ne décrit aucun PAT en lecture seule : la capacité d’accès à l’API Notion permet de lire, de créer et de mettre à jour du contenu. Si une tâche nécessite uniquement de lire quelques pages, une connexion interne disposant seulement de l’autorisation Lire le contenu est une clé plus sûre. Lorsque vous perdez l’accès à une page ou quittez l’espace de travail, le jeton perd lui aussi cet accès.

Option 2 : créer un jeton de connexion interne

Une connexion interne est un utilisateur bot rattaché à un seul espace de travail. Utilisez-la pour les automatisations dont dépend votre équipe, ou pour tout outil qui ne doit accéder qu’à quelques pages plutôt qu’à toutes celles que vous pouvez ouvrir. Les anciens guides parlent d’« intégration interne » et désignent son jeton par « secret d’intégration interne » ou « jeton d’intégration ».

1. Vérifiez que vous êtes propriétaire de l’espace de travail. Seuls les propriétaires peuvent créer des connexions. Si ce n’est pas votre cas, demandez à un propriétaire ou créez un espace de travail personnel gratuit pour faire des essais, comme le suggère la FAQ de Notion.
2. Créez la connexion. Dans la section dédiée aux développeurs de la barre latérale, ou sur notion.so/developers, ouvrez Connexions internes, cliquez sur Créer une nouvelle connexion, saisissez un nom et choisissez l’espace de travail. Une connexion ne peut pas être transférée vers un autre espace de travail par la suite ; il faudrait en créer une nouvelle dans cet autre espace.
3. Copiez le jeton API. Ouvrez l’onglet Configuration de la connexion et copiez le jeton API. Les propriétaires peuvent aussi y accéder depuis Paramètres → Connexions : le menu ••• à côté de la connexion propose une option pour récupérer le jeton.
4. Définissez les autorisations dans le même onglet (la liste figure ci-dessous).
5. Donnez-lui accès à des pages. Une nouvelle connexion n’a accès à rien, et toutes les requêtes échouent tant que vous ne partagez aucun contenu avec elle. Dans l’onglet Accès au contenu, cliquez sur Modifier l’accès et sélectionnez des pages et des bases de données. Vous pouvez aussi ouvrir une page dans Notion, cliquer sur ••• en haut à droite, repérer Connexions, choisir Ajouter une connexion et rechercher la vôtre. Partager une page donne également accès à ses sous-pages.

Les autorisations limitent les actions que le jeton peut effectuer, même sur les pages auxquelles il a accès. La documentation de Notion recommande de ne demander que le strict minimum :

• Lire le contenu, Mettre à jour le contenu, Insérer du contenu, dans n’importe quelle combinaison. Un export nécessite uniquement l’autorisation Lire le contenu. Un formulaire qui ajoute des lignes nécessite uniquement l’autorisation Insérer du contenu. Un script qui définit un statut nécessite uniquement l’autorisation Mettre à jour le contenu.
• Lire les commentaires, Insérer des commentaires.
• Informations sur les utilisateurs : aucune, sans adresses e-mail ou avec adresses e-mail.

La connexion étant un utilisateur à part entière, ses accès ne dépendent pas des personnes. Si le membre de l’équipe qui a partagé une page quitte l’espace de travail, la connexion conserve l’accès à cette page. Chaque propriétaire de l’espace de travail peut voir toutes les connexions internes, y compris celles créées par d’autres.

Option 3 : OAuth pour les applications utilisées par d’autres personnes

Si vous développez un produit, ne demandez pas aux utilisateurs de coller des jetons. Créez plutôt une connexion publique : chaque utilisateur se connecte via la fenêtre OAuth de Notion et choisit les pages que votre application peut consulter. Échangez le code OAuth contre un jeton sur un serveur que vous contrôlez. Le secret client ne doit jamais être transmis à un navigateur, et les points de terminaison de Notion dédiés aux jetons OAuth sont volontairement inaccessibles au code exécuté dans un navigateur. IVGraph se connecte de cette façon : vous choisissez les pages dans la fenêtre de Notion et n’avez jamais à manipuler de clé.

Testez la clé avec une seule requête

Stockez le jeton dans une variable d’environnement plutôt que dans votre code. Sur macOS ou Linux :

export NOTION_API_KEY="ntn_…"

Dans Windows PowerShell, utilisez $env:NOTION_API_KEY = "ntn_…". Demandez ensuite à Notion à qui appartient le jeton :

curl https://api.notion.com/v1/users/me \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

Une clé valide renvoie un utilisateur de type bot ; dans le cas d’un jeton d’accès personnel, vous en êtes le propriétaire. Vérifiez ensuite ce à quoi la clé donne accès. Une recherche sans requête renvoie toutes les pages et sources de données accessibles au jeton. Ce filtre ne conserve que les sources de données de vos bases de données, chacune avec son propre ID et celui de sa base de données parente :

curl -X POST https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "object", "value": "data_source"}}'

Chaque requête doit inclure l’en-tête Notion-Version ; 2026-03-11 est la version la plus récente. En JavaScript, le SDK officiel n’a besoin du jeton qu’une seule fois et réessaie automatiquement les requêtes bloquées par la limite de débit. Sa version actuelle envoie 2025-09-03 par défaut. Définissez donc explicitement la version :

import { Client } from "@notionhq/client";

const notion = new Client({
  auth: process.env.NOTION_API_KEY,
  notionVersion: "2026-03-11",
});

const me = await notion.users.me({});
console.log(me.type, me.name);

Où trouver l’ID d’une page, d’une base de données ou d’un bloc

Chaque page, base de données et bloc dans Notion possède un identifiant : un UUID de 32 caractères hexadécimaux. Dans les liens, il apparaît sans tirets, et l’API l’accepte avec ou sans tirets. Avec les tirets, les caractères sont regroupés selon le format 8-4-4-4-12 : 1429989fe8ac4effbc8f57f56486db54 devient donc 1429989f-e8ac-4eff-bc8f-57f56486db54.

Le moyen le plus rapide : le mode développeur

Lorsque le mode développeur est activé, une barre de développement en bas de Notion affiche l’ID de la page, du bloc, de la base de données ou de la source de données que vous consultez. Faites un clic droit sur un bloc ou une base de données et ouvrez la section Développeur pour copier directement un ID. Comme le paramètre lui-même, cette fonctionnalité est disponible dans le navigateur et l’application de bureau, mais pas sur mobile.

À partir d’un lien

Copiez le lien d’une page via Partager → Copier le lien, ou celui d’un bloc depuis son menu ⋮⋮ avec Copier le lien du bloc. Dans chaque type de lien, l’ID se trouve à un emplacement fixe :

Page
https://www.notion.so/acme/Launch-plan-1429989fe8ac4effbc8f57f56486db54

Database (full-page view)
https://www.notion.so/acme/248104cd477e80fdb757e945d38000bd?v=8f1c2a7e3b5d4c6e9a0b1c2d3e4f5a6b

Block
https://www.notion.so/acme/Launch-plan-1429989fe8ac4effbc8f57f56486db54#5c7d2e9a1b3f4c8d9e0f1a2b3c4d5e6f

Depuis juin 2026, les liens vers les pages dans les réponses de l’API utilisent un autre format : https://app.notion.com/p/…. L’identifiant correspond toujours aux 32 derniers caractères, et les anciens liens notion.so continuent de fonctionner.

Deux cas posent problème :

• Bases de données intégrées. Une base de données intégrée se trouve à l’intérieur d’une page : la barre d’adresse affiche donc l’identifiant de cette page. Ouvrez d’abord la base de données en pleine page, puis copiez le lien.
• Vues liées. Si le menu des vues d’une base de données propose Ouvrir la base de données source, vous consultez une vue liée. L’API ne peut pas lire les bases de données liées : ouvrez la source, utilisez son identifiant et partagez-la avec votre connexion.

Dans une base de données, une propriété de formule contenant id() affiche l’ID de la page de chaque ligne sans tirets, et id(prop("Project").first()) renvoie l’ID d’une page liée. C’est utile lorsqu’un outil d’automatisation vous demande les ID des lignes.

L’identifiant de la source de données, celui qui ne figure pas dans le lien

Depuis la version 2025-09-03 de l’API, une base de données est un conteneur regroupant une ou plusieurs sources de données. La source de données contient les propriétés et les lignes. Les requêtes sur les lignes et la création de pages dans une base de données passent donc par les points de terminaison sous /v1/data_sources/. Ceux-ci attendent l’identifiant d’une source de données, et non l’identifiant de la base de données présent dans le lien. Trois façons de l’obtenir :

• Dans Notion : ouvrez le menu des paramètres de la base de données, accédez à Gérer les sources de données et cliquez sur Copier l’ID de la source de données. Si le mode développeur est activé, un clic droit sur la base de données fonctionne aussi.
• Via l’API : récupérez la base de données et consultez sa liste data_sources.
• Via la recherche : le filtre data_source présenté ci-dessus.

curl https://api.notion.com/v1/databases/248104cd477e80fdb757e945d38000bd \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2026-03-11"

# the part of the response you need
{
  "object": "database",
  "id": "248104cd-477e-80fd-b757-e945d38000bd",
  "data_sources": [
    { "id": "248104cd-477e-80af-bc30-000bd28de8f9", "name": "Grocery list" }
  ]
}

Interrogez ensuite les lignes avec POST /v1/data_sources/248104cd-477e-80af-bc30-000bd28de8f9/query. Aujourd’hui, la plupart des bases de données n’ont qu’une seule source de données, mais ne partez pas de ce principe pour votre implémentation. Le guide de mise à niveau de Notion vous met en garde : dès qu’une personne ajoute une deuxième source à une base de données, les connexions qui utilisent encore une ancienne version de l’API ne trouvent plus cette base dans les résultats de recherche, et leurs opérations de lecture et d’écriture ainsi que leurs requêtes sur cette base échouent.

Dans le code

Le SDK JavaScript officiel se charge de cette analyse pour vous : extractPageId, extractDatabaseId et extractBlockId sont disponibles depuis septembre 2025. Ces fonctions renvoient l’ID avec des tirets et privilégient l’ID présent dans le chemin plutôt que dans les paramètres de requête, pour qu’un lien vers une base de données ne vous renvoie pas par erreur l’ID de la vue.

import { extractDatabaseId } from "@notionhq/client";

extractDatabaseId("https://www.notion.so/acme/248104cd477e80fdb757e945d38000bd?v=8f1c2a7e3b5d4c6e9a0b1c2d3e4f5a6b");
// "248104cd-477e-80fd-b757-e945d38000bd"

Corrigez les premières erreurs que vous rencontrerez

Les réponses d’erreur contiennent un statut HTTP, un code et un message lisible. Ces six erreurs couvrent presque tous les problèmes rencontrés le premier jour :

Trois autres problèmes qui n’ont pas l’air d’être des erreurs :

• Les propriétés Relation sont vides. Partagez aussi la base de données liée avec la connexion. Sinon, les propriétés basées sur cette relation ne sont pas incluses dans la réponse. Le fonctionnement des relations est expliqué dans notre guide des relations Notion.
• La recherche ne renvoie aucun résultat. Un jeton ne permet de trouver que les éléments auxquels il a accès. Pour une connexion, il s’agit des pages partagées avec elle et de leurs pages enfants.
• Une requête qui fonctionnait hier échoue aujourd’hui. Un PAT a peut-être expiré, un administrateur l’a peut-être révoqué ou quelqu’un a renouvelé le jeton de la connexion. Pour les connexions internes et publiques, l’onglet État des outils de développement répertorie les requêtes des dernières 24 heures, avec leurs codes d’erreur et les cas où la limite de débit a été atteinte.

Limites de débit de l’API Notion en 2026

Notion a modifié ses limites le 9 septembre 2026. Les réponses plus anciennes évoquent une limite unique de trois requêtes par seconde en moyenne, avec des temps d’attente pouvant atteindre 15 minutes. Désormais, la limite dépend du forfait et se calcule par minute. Voici ce qu’indique la page de Notion consacrée aux limites de requêtes :

Le quota par connexion est réinitialisé toutes les 60 secondes et peut être consommé en une seule rafale. Lorsqu’une limite est dépassée, Notion renvoie une réponse HTTP 429, le code rate_limited et un en-tête Retry-After indiquant le délai d’attente en secondes. Pour la limite par connexion, ce délai ne dépasse jamais 60 secondes ; la limite partagée à l’échelle de l’espace de travail peut imposer une attente plus longue. Le champ additional_data.rate_limit_reason indique quelle limite vous avez atteinte. Une réponse 529 service_overload signifie que Notion est lui-même surchargé : traitez-la comme une réponse 429. Les appels aux outils Notion MCP sont soumis aux mêmes limites.

Comment rester dans ces limites :

1. Faites passer les requêtes par une seule file d’attente, plutôt que par des processus de traitement parallèles qui réessaient chacun de leur côté.
2. En cas d’erreur 429 ou 529, attendez le délai indiqué par Retry-After, puis réessayez. Si l’erreur se reproduit, augmentez le délai de façon exponentielle en y ajoutant une légère variation aléatoire, et limitez le nombre de tentatives.
3. Pour la plupart des erreurs 400, ne réessayez pas : corrigez la requête. Une erreur 429 avec le motif public_api_request_blocked ne se résoudra pas non plus en attendant ; contactez l’assistance Notion.
4. Avant de répéter une opération d’écriture ayant renvoyé une erreur 503, lisez additional_data.retry_guidance. La modification est peut-être déjà enregistrée : répéter l’opération l’appliquerait une deuxième fois.

Conservez la clé en lieu sûr

Toute personne disposant du jeton peut effectuer toutes les actions qu’il autorise. Pour un PAT, cela concerne tout ce que vous pouvez ouvrir ; pour une connexion, toutes les pages partagées avec elle.

• Stockez-le en dehors de votre code : dans une variable d’environnement pour le travail en local, avec .env dans .gitignore, et dans un gestionnaire de secrets en production.
• Ne l’intégrez jamais à une page web. L’API Notion accepte les requêtes provenant du code exécuté dans le navigateur : un jeton intégré à une page accessible à d’autres personnes peut donc être utilisé par quiconque en consulte le code source.
• Ne le collez pas dans des discussions, des tickets d’assistance ou des outils de suivi des problèmes, y compris dans vos conversations avec des assistants IA.
• Utilisez un jeton par outil et par environnement, pour pouvoir en révoquer un sans perturber le reste.
• Accordez le minimum d’autorisations. Pour un outil tiers, une connexion interne qui n’a accès qu’aux pages que vous partagez est plus sûre qu’un PAT qui a accès à tout ce à quoi vous avez accès. Définissez une courte durée de validité pour les PAT utilisés à titre expérimental.
• Activez la détection des secrets dans votre dépôt et votre système d’intégration continue. Le préfixe ntn_ permet aux outils de détection de reconnaître les jetons Notion.

En cas de fuite d’un jeton, procédez dans cet ordre. Dans Notion, ouvrez Paramètres → Connexions → Développer ou gérer les connexions, trouvez la connexion ou le jeton, puis cliquez sur Actualiser pour une connexion interne, ou révoquez le PAT. Remplacez l’ancienne valeur partout où elle était utilisée. Vérifiez ensuite les modifications récentes de vos pages et bases de données, et recherchez les connexions que vous ne reconnaissez pas. Les administrateurs de l’espace de travail peuvent également révoquer le PAT de n’importe quel membre depuis Paramètres → Connexions, mais ils ne peuvent jamais voir ni copier le jeton lui-même.

Quand vous n’avez pas besoin de clé API

• Applications d’IA. Claude, ChatGPT, Cursor, Codex et VS Code se connectent au serveur MCP hébergé par Notion via OAuth : vous n’avez donc aucune clé à créer. Notre assistant de configuration MCP pour Notion vous fournit la configuration exacte pour chaque application. Deux exceptions : avec les forfaits Business et Enterprise, un propriétaire d’espace de travail peut créer un jeton MCP pour les clients qui ne peuvent pas ouvrir de fenêtre de connexion ; le serveur MCP open source autohébergé utilise quant à lui un jeton d’API, bien que Notion n’en assure plus activement la maintenance.
• Applications utilisant la connexion via Notion. Un outil qui ouvre la fenêtre de Notion et vous demande de sélectionner des pages utilise une connexion publique : vous ne voyez jamais de jeton.
• Visualiser les liens dans votre espace de travail. On rassemble souvent les identifiants des pages et des bases de données pour cartographier les relations à la main. IVGraph se connecte via la fenêtre OAuth de Notion et représente chaque page, chaque mention et chaque Relation de base de données sous forme de graphe 3D interactif. C’est gratuit jusqu’à 500 nœuds.

Si un agent doit lire ce graphe, IVGraph propose une API pour les agents en lecture seule, avec son propre jeton de service, dans les offres Pro et Max : recherche, contenu des pages, pages voisines et chemins entre les pages. Il n’existe pas encore de serveur MCP pour IVGraph.

FAQ