So erhältst du einen Notion-API-Schlüssel und findest die IDs, die du für deine Anfragen benötigst

Ein Notion-API-Schlüssel ist das Token, das dein Code bei jeder Anfrage an die Notion-API mitsendet. 2026 gibt es drei Arten: ein persönliches Zugriffstoken, das in deinem Namen handelt, ein internes Verbindungstoken für Automatisierungen im Team und OAuth für Apps, die andere installieren. Im Folgenden erfährst du, wie du sie jeweils erstellst, ihnen Zugriff auf deine Seiten gibst, die für deine Anfragen benötigten IDs von Seiten, Datenbanken und Datenquellen findest und die Fehler behebst, auf die fast alle beim ersten Versuch stoßen.

Welchen Notion-API-Schlüssel brauchst du?

Die Entwicklerdokumentation von Notion nennt drei Möglichkeiten zur Authentifizierung. Sie unterscheiden sich darin, wessen Berechtigungen das Token übernimmt, worauf es Zugriff hat und wer es erstellen darf.

So triffst du schnell eine Entscheidung:

• Ein Skript, Notebook oder Tool, das nur du nutzt: ein persönliches Zugriffstoken. Du musst nichts teilen und bist in zwei Minuten startklar.
• Eine Automatisierung, auf die sich dein Team verlässt: eine interne Verbindung. Sie funktioniert auch dann weiter, wenn die Person, die sie eingerichtet hat, das Team verlässt, und hat nur Zugriff auf die Seiten, die du mit ihr teilst.
• Eine App, die andere installieren: eine öffentliche Verbindung mit OAuth. Fordere deine Nutzer niemals dazu auf, ein Token einzufügen.
• Claude, ChatGPT, Cursor oder eine andere KI-App: in der Regel gar kein Schlüssel. Über den von Notion gehosteten MCP-Server meldest du dich mit OAuth an; wie die Einrichtung funktioniert, zeigt dir unser Leitfaden zu Notion MCP.

Option 1: Persönliches Zugriffstoken erstellen

Ein persönliches Zugriffstoken (PAT) handelt in deinem Namen – mit deiner Workspace-Mitgliedschaft und deinen Seitenberechtigungen. Notions eigene API-Schnellstartanleitung beginnt mit einem solchen Token, weil du außer dem Token nichts einrichten musst.

1. Aktiviere den Entwicklermodus. Öffne in Notion die Einstellungen, suche nach Entwicklermodus und aktiviere ihn. Das ist eine lokale Einstellung: Du musst ihn im Browser und in der Desktop-App jeweils separat aktivieren. Auf Mobilgeräten ist er nicht verfügbar.
2. Öffne die Token-Liste. In der Seitenleiste erscheint ein Bereich für Entwickler. Öffne Persönliche Zugriffstoken und klicke auf Neues Token. Der direkte Link lautet notion.so/developers/tokens.
3. Vergib einen Namen und lege den Geltungsbereich fest. Wähle die Berechtigung Notion API (füge Workers nur hinzu, wenn du Notion Workers bereitstellst) und eine Gültigkeitsdauer: 7, 30, 90 oder 180 Tage oder 1 Jahr (Standardeinstellung). Falls eine Workspace-Auswahl erscheint, wähle den Workspace aus: Ein Token gehört zu genau einem Workspace.
4. Klicke auf „Token erstellen“ und kopiere den Wert sofort. Notion zeigt ihn nur einmal an und danach nie wieder, auch Admins nicht. Speichere ihn in einem Passwortmanager oder im Secret-Speicher deines Projekts.

Neue Tokens beginnen mit ntn_. Notion hat am 25. September 2024 das bisherige Präfix secret_ ersetzt; ältere Tokens funktionieren weiterhin. Prüfe das Präfix aber nicht in deinem Code: Notion weist darauf hin, dass sich das Format ändern kann, und bittet Entwickler, Tokens als opake Zeichenfolgen zu behandeln.

Du kannst keinen Token erstellen?

Gäste und eingeschränkte Mitglieder können überhaupt keine PATs erstellen. Für alle anderen legt der Tarif fest, wer einen PAT mit Zugriff auf die Notion API erstellen darf:

Bitte im Business- oder Enterprise-Plan einen Workspace-Inhaber, dies unter Einstellungen → Verbindungen zu erlauben. Wenn ein Admin die Richtlinie später einschränkt, funktionieren deine vorhandenen Tokens nicht mehr und geben unauthorized zurück.

Worauf ein PAT zugreifen kann

Alles, was du in diesem Workspace öffnen kannst: Seiten, Datenbanken, Kommentare und Dateien. Seiten müssen nicht für den Token freigegeben werden. Das macht PATs schnell einsatzbereit – und einen geleakten PAT zugleich kostspielig. In der Dokumentation von Notion ist kein schreibgeschützter PAT beschrieben: Die Notion-API-Berechtigung erlaubt das Lesen, Erstellen und Aktualisieren. Wenn eine Aufgabe nur Lesezugriff auf wenige Seiten erfordert, ist eine interne Verbindung mit ausschließlich der Berechtigung Inhalte lesen der sicherere Zugangsschlüssel. Wenn du den Zugriff auf eine Seite verlierst oder den Workspace verlässt, verliert auch der Token den entsprechenden Zugriff.

Option 2: Token für eine interne Verbindung erstellen

Eine interne Verbindung ist ein Bot-Benutzer, der zu einem Workspace gehört. Nutze sie für Automatisierungen, auf die das Team angewiesen ist, oder für Tools, die nur auf einige wenige Seiten zugreifen sollen statt auf alles, was du öffnen kannst. In älteren Anleitungen heißt sie „interne Integration“, und ihr Token wird als „geheimer Schlüssel der internen Integration“ oder „Integrationstoken“ bezeichnet.

1. Prüfe, ob du Workspace-Besitzer bist. Nur Besitzer können Verbindungen erstellen. Falls du keiner bist, bitte einen Besitzer darum oder erstelle einen kostenlosen persönlichen Workspace zum Experimentieren, wie in den FAQ von Notion empfohlen.
2. Erstelle die Verbindung. Öffne im Entwicklerbereich der Seitenleiste oder unter notion.so/developers den Bereich Interne Verbindungen, klicke auf Neue Verbindung erstellen, gib einen Namen ein und wähle den Workspace aus. Eine Verbindung lässt sich später nicht in einen anderen Workspace verschieben; dort müsstest du eine neue erstellen.
3. Kopiere das API-Token. Öffne den Tab Konfiguration der Verbindung und kopiere das API-Token. Besitzer finden es auch unter Einstellungen → Verbindungen: Im Menü ••• neben der Verbindung gibt es eine Option zum Abrufen des Tokens.
4. Lege die Berechtigungen fest – im selben Tab (die Liste findest du weiter unten).
5. Gib der Verbindung Zugriff auf Seiten. Eine neue Verbindung hat auf nichts Zugriff, und jede Anfrage schlägt fehl, bis du etwas freigibst. Klicke im Tab Inhaltszugriff auf Zugriff bearbeiten und wähle Seiten und Datenbanken aus. Oder öffne eine Seite in Notion, klicke oben rechts auf •••, suche den Bereich Verbindungen, wähle Verbindung hinzufügen und suche nach deiner Verbindung. Wenn du eine Seite freigibst, werden auch ihre Unterseiten freigegeben.

Berechtigungen begrenzen, was das Token tun kann – auch auf Seiten, die es einsehen kann. Die Notion-Dokumentation empfiehlt, nur die nötigsten Berechtigungen anzufordern:

• Inhalte lesen, Inhalte aktualisieren, Inhalte einfügen, in beliebiger Kombination. Für einen Export brauchst du nur „Inhalte lesen“. Ein Formular, das Zeilen hinzufügt, braucht nur „Inhalte einfügen“. Ein Skript, das einen Status setzt, braucht nur „Inhalte aktualisieren“.
• Kommentare lesen, Kommentare einfügen.
• Nutzerinformationen: keine, ohne E-Mail-Adressen oder mit E-Mail-Adressen.

Da die Verbindung ein eigener Nutzer ist, hängt ihr Zugriff nicht von einzelnen Personen ab. Wenn das Teammitglied, das eine Seite geteilt hat, den Workspace verlässt, behält die Verbindung den Zugriff auf diese Seite. Alle Workspace-Besitzer können sämtliche internen Verbindungen sehen – auch die, die andere erstellt haben.

Option 3: OAuth für Apps, die andere nutzen

Wenn du ein Produkt entwickelst, fordere deine Nutzer nicht auf, Tokens einzufügen. Erstelle stattdessen eine öffentliche Verbindung: Jeder Nutzer meldet sich über das OAuth-Fenster von Notion an und wählt aus, welche Seiten deine App sehen darf. Tausche den OAuth-Code auf einem Server, den du kontrollierst, gegen ein Token ein. Das Client-Secret darf niemals in einen Browser gelangen, und die OAuth-Token-Endpunkte von Notion sind bewusst nicht für Browser-Code zugänglich. So verbindet sich auch IVGraph: Du wählst die Seiten im Notion-Fenster aus und hast dabei nie mit einem Schlüssel zu tun.

Teste den Schlüssel mit einer Anfrage

Speichere das Token in einer Umgebungsvariablen statt in deinem Code. Unter macOS oder Linux:

export NOTION_API_KEY="ntn_…"

In Windows PowerShell lautet der Befehl $env:NOTION_API_KEY = "ntn_…". Frag dann Notion, wem der Token gehört:

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

Ein funktionierender Schlüssel gibt einen Benutzer vom Typ bot zurück; bei einem persönlichen Zugriffstoken bist du der Inhaber. Prüfe als Nächstes, worauf der Schlüssel zugreifen kann. Eine Suche ohne Suchbegriff gibt jede Seite oder Datenquelle zurück, auf die das Token zugreifen kann. Dieser Filter beschränkt die Ergebnisse auf die Datenquellen deiner Datenbanken, jeweils mit ihrer eigenen ID und der ID ihrer übergeordneten Datenbank:

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"}}'

Jede Anfrage benötigt den Header Notion-Version; 2026-03-11 ist die neueste Version. In JavaScript übergibst du dem offiziellen SDK das Token einmalig. Anfragen, die wegen des Ratenlimits abgewiesen werden, wiederholt es für dich. Die aktuelle SDK-Version sendet standardmäßig 2025-09-03, also lege die Version explizit fest:

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);

Wo du die ID einer Seite, Datenbank oder eines Blocks findest

Jede Seite, jede Datenbank und jeder Block in Notion hat eine ID: eine UUID aus 32 hexadezimalen Zeichen. In Links wird sie ohne Bindestriche angezeigt, die API akzeptiert sie mit oder ohne Bindestriche. Mit Bindestrichen ist sie nach dem Muster 8-4-4-4-12 gruppiert, sodass aus 1429989fe8ac4effbc8f57f56486db54 die UUID 1429989f-e8ac-4eff-bc8f-57f56486db54 wird.

Der schnellste Weg: Entwicklermodus

Wenn der Entwicklermodus aktiviert ist, zeigt eine Entwicklerleiste am unteren Rand von Notion die ID der Seite, des Blocks, der Datenbank oder der Datenquelle an, die du gerade ansiehst. Klicke mit der rechten Maustaste auf einen Block oder eine Datenbank und öffne den Bereich Entwickler, um eine ID direkt zu kopieren. Wie die Einstellung selbst ist auch diese Funktion im Browser und in der Desktop-App verfügbar, nicht aber auf Mobilgeräten.

Über einen Link

Kopiere den Link zu einer Seite über Teilen → Link kopieren oder den Link zu einem Block über dessen ⋮⋮-Menü mit Link zum Block kopieren. Bei beiden Linktypen steht die ID an einer festen Stelle:

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

Seit Juni 2026 haben Seitenlinks in API-Antworten ein anderes Format: https://app.notion.com/p/…. Die ID besteht weiterhin aus den letzten 32 Zeichen, und ältere notion.so-Links funktionieren nach wie vor.

Zwei Fälle sorgen für Verwirrung:

• Inline-Datenbanken. Eine Inline-Datenbank befindet sich innerhalb einer Seite, daher zeigt die Adressleiste die ID der Seite an. Öffne die Datenbank zuerst als vollständige Seite und kopiere dann den Link.
• Verknüpfte Ansichten. Wenn im Ansichtsmenü einer Datenbank Quelldatenbank öffnen angeboten wird, siehst du eine verknüpfte Ansicht. Die API kann verknüpfte Datenbanken nicht lesen: Öffne die Quelldatenbank, verwende ihre ID und teile sie mit deiner Verbindung.

In einer Datenbank zeigt eine Formel-Eigenschaft mit id() die Seiten-ID jeder Zeile ohne Bindestriche an. Mit id(prop("Project").first()) erhältst du die ID einer verknüpften Seite. Das ist hilfreich, wenn ein Automatisierungstool dich nach Zeilen-IDs fragt.

Die Datenquellen-ID, die nicht im Link steht

Seit der API-Version 2025-09-03 ist eine Datenbank ein Container für eine oder mehrere Datenquellen. Die Datenquelle enthält die Eigenschaften und Zeilen. Deshalb laufen das Abfragen von Zeilen und das Erstellen von Seiten in einer Datenbank über Endpunkte unter /v1/data_sources/. Diese erwarten eine Datenquellen-ID, nicht die Datenbank-ID aus dem Link. So findest du die Datenquellen-ID – auf drei Wegen:

• In Notion: Öffne das Einstellungsmenü der Datenbank, gehe zu Datenquellen verwalten und klicke auf Datenquellen-ID kopieren. Bei aktiviertem Entwicklermodus geht das auch per Rechtsklick auf die Datenbank.
• Über die API: Rufe die Datenbank ab und lies ihre data_sources-Liste aus.
• Über die Suche: mit dem oben gezeigten data_source-Filter.

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" }
  ]
}

Frage dann die Zeilen mit POST /v1/data_sources/248104cd-477e-80af-bc30-000bd28de8f9/query ab. Die meisten Datenbanken haben heute nur eine Datenquelle, aber verlass dich beim Entwickeln nicht darauf. Notions Upgrade-Leitfaden warnt: Sobald jemand einer Datenbank eine zweite Datenquelle hinzufügt, finden Verbindungen, die noch eine ältere API-Version nutzen, diese Datenbank nicht mehr in der Suche. Auch Lese- und Schreibzugriffe auf diese Datenbank sowie entsprechende Abfragen schlagen dann fehl.

Im Code

Das offizielle JavaScript-SDK übernimmt das Parsen für dich: extractPageId, extractDatabaseId und extractBlockId kamen im September 2025 hinzu. Sie geben die ID mit Bindestrichen zurück und bevorzugen die ID im Pfad gegenüber Abfrageparametern, damit du bei einem Datenbanklink nicht versehentlich die ID der Ansicht erhältst.

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

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

Behebe die Fehler, auf die du zuerst stößt

Fehlerantworten enthalten einen HTTP-Status, einen code und eine verständliche message. Diese sechs decken fast alle Probleme am ersten Tag ab:

Drei weitere Probleme, die nicht wie Fehler aussehen:

• Eigenschaften vom Typ „Relation“ werden leer zurückgegeben. Gib auch die verknüpfte Datenbank für die Verbindung frei. Andernfalls werden die Eigenschaften, die auf dieser Relation basieren, in der Antwort ausgelassen. Wie Relationen funktionieren, erklären wir in unserem Leitfaden zu Relationen in Notion.
• Die Suche liefert keine Ergebnisse. Ein Token findet nur Inhalte, auf die es zugreifen kann. Bei einer Verbindung sind das die für sie freigegebenen Seiten und deren Unterseiten.
• Eine Anfrage, die gestern noch funktioniert hat, schlägt heute fehl. Möglicherweise ist ein PAT abgelaufen, ein Admin hat es widerrufen oder jemand hat den Token der Verbindung erneuert. Bei internen und öffentlichen Verbindungen listet der Tab Status in den Entwicklertools die Anfragen der letzten 24 Stunden mit ihren Fehlercodes und den Fällen auf, in denen das Anfragelimit überschritten wurde.

Anfragelimits der Notion-API im Jahr 2026

Notion hat seine Limits am 9. September 2026 geändert. Ältere Antworten beschreiben ein einheitliches Limit von durchschnittlich drei Anfragen pro Sekunde mit Wartezeiten von bis zu 15 Minuten. Jetzt hängt das Limit vom Tarif ab und wird pro Minute bemessen. Das steht auf Notions Seite zu den Anfragelimits:

Das Kontingent pro Verbindung wird alle 60 Sekunden zurückgesetzt und kann auf einmal aufgebraucht werden. Wird ein Limit überschritten, antwortet Notion mit HTTP 429, dem Code rate_limited und einem Retry-After-Header mit der Wartezeit in Sekunden. Beim Limit pro Verbindung beträgt diese Wartezeit nie mehr als 60 Sekunden; beim gemeinsamen Workspace-Limit kann sie länger ausfallen. Das Feld additional_data.rate_limit_reason gibt an, welches Limit du erreicht hast. Der HTTP-Statuscode 529 mit service_overload bedeutet, dass Notion selbst überlastet ist: Behandle ihn wie HTTP 429. Aufrufe von Notion MCP-Tools werden auf dieselben Limits angerechnet.

So bleibst du innerhalb dieser Grenzen:

1. Sende Anfragen über eine einzige Warteschlange, nicht über parallele Worker, die jeweils eigenständig Wiederholungsversuche starten.
2. Warte bei 429 oder 529 die in Retry-After angegebene Zeit ab und versuche es erneut. Tritt der Fehler wieder auf, verlängere die Wartezeit exponentiell mit einer kleinen zufälligen Abweichung und begrenze die Anzahl der Versuche.
3. Wiederhole Anfragen bei den meisten 400-Fehlern nicht, sondern korrigiere sie. Auch ein 429 mit dem Grund public_api_request_blocked lässt sich nicht durch Warten beheben; kontaktiere den Notion-Support.
4. Lies additional_data.retry_guidance, bevor du einen Schreibvorgang wiederholst, der 503 zurückgegeben hat. Die Änderung ist möglicherweise bereits gespeichert und würde durch eine Wiederholung doppelt angewendet.

Bewahre den Schlüssel sicher auf

Wer den Token hat, kann alles tun, was er erlaubt. Bei einem PAT gilt das für alles, was du öffnen kannst; bei einer Verbindung für jede Seite, die mit ihr geteilt wurde.

• Speichere es außerhalb deines Codes: für die lokale Arbeit in einer Umgebungsvariablen, wobei .env in .gitignore eingetragen ist, und in der Produktionsumgebung in einem Secret-Manager.
• Bette es niemals in eine Webseite ein. Die Notion-API akzeptiert Anfragen aus Browser-Code. Ein Token, das in eine für andere zugängliche Seite eingebettet ist, kann daher von allen genutzt werden, die sich deren Quelltext ansehen.
• Füge es nicht in Chats, Support-Tickets oder Issue-Tracker ein – auch nicht in Gespräche mit KI-Assistenten.
• Verwende für jedes Tool und jede Umgebung ein eigenes Token, damit beim Widerruf eines Tokens alles andere weiterhin funktioniert.
• Vergib nur die nötigsten Berechtigungen. Für ein Drittanbieter-Tool ist eine interne Verbindung, die nur die von dir geteilten Seiten sehen kann, sicherer als ein PAT, das alles sehen kann, was auch du sehen kannst. Gib PATs für Experimente eine kurze Gültigkeitsdauer.
• Aktiviere die Suche nach Secrets in deinem Repository und deiner CI. Das Präfix ntn_ dient dazu, dass Scanner Notion-Tokens erkennen können.

Wenn ein Token offengelegt wird, gehe in dieser Reihenfolge vor. Öffne in Notion Einstellungen → Verbindungen → Verbindungen entwickeln oder verwalten, suche die Verbindung oder das Token und klicke bei einer internen Verbindung auf Aktualisieren oder widerrufe das PAT. Ersetze den alten Wert überall dort, wo er verwendet wurde. Prüfe anschließend die letzten Änderungen an deinen Seiten und Datenbanken und suche nach Verbindungen, die du nicht kennst. Workspace-Admins können das PAT jedes Mitglieds auch unter Einstellungen → Verbindungen widerrufen, das Token selbst aber niemals einsehen oder kopieren.

Wann du keinen API-Schlüssel brauchst

• KI-Apps. Claude, ChatGPT, Cursor, Codex und VS Code verbinden sich über OAuth mit dem von Notion gehosteten MCP-Server. Du musst also keinen Schlüssel erstellen. Unsere Einrichtungshilfe für Notion MCP liefert dir die genaue Konfiguration für jede App. Es gibt zwei Ausnahmen: In den Tarifen Business und Enterprise können Workspace-Inhaber einen MCP-Token für Clients erstellen, die kein Anmeldefenster öffnen können. Der quelloffene, selbst gehostete MCP-Server benötigt dagegen einen API-Token, wird von Notion allerdings nicht mehr aktiv gepflegt.
• Apps mit Notion-Anmeldung. Ein Tool, das das Notion-Fenster öffnet und dich auffordert, Seiten auszuwählen, nutzt eine öffentliche Verbindung. Einen Token bekommst du dabei nie zu sehen.
• Verbindungen in deinem Workspace entdecken. Viele sammeln IDs von Seiten und Datenbanken, um Relationen von Hand abzubilden. IVGraph verbindet sich über das OAuth-Fenster von Notion und stellt jede Seite, jede Erwähnung und jede Datenbank-Relation in einem interaktiven 3D-Graphen dar. Für bis zu 500 Knoten ist IVGraph kostenlos.

Wenn ein Agent diesen Graphen lesen soll, bietet IVGraph in den Pro- und Max-Tarifen eine API für Agenten mit eigenem Service-Token und reinem Lesezugriff: Suche, Seiteninhalte, benachbarte Seiten und Pfade zwischen Seiten. Einen IVGraph-MCP-Server gibt es noch nicht.

Häufige Fragen