Cómo obtener una clave de API de Notion y encontrar los ID necesarios para tus solicitudes

Una clave de API de Notion es el token que tu código envía con cada solicitud a la API de Notion. En 2026 hay tres tipos: un token de acceso personal que actúa en tu nombre, un token de conexión interna para automatizaciones del equipo y OAuth para aplicaciones que instalan otras personas. A continuación, verás cómo crear cada uno, darle acceso a tus páginas, encontrar los ID de página, base de datos y fuente de datos que necesitan tus solicitudes y resolver los errores con los que casi todo el mundo se encuentra en el primer intento.

¿Qué clave de API de Notion necesitas?

La documentación para desarrolladores de Notion recoge tres formas de autenticación. Se diferencian en de quién son los permisos que tiene el token, qué puede ver y quién está autorizado a crearlo.

Una forma rápida de elegir:

• Un script, un cuaderno o una herramienta que solo usas tú: un token de acceso personal. No tienes que compartir nada y lo tendrás funcionando en dos minutos.
• Una automatización de la que depende el equipo: una conexión interna. Sigue funcionando cuando se va la persona que la configuró y solo puede acceder a las páginas que compartes con ella.
• Una app que instalan otras personas: una conexión pública con OAuth. Nunca pidas a tus usuarios que peguen un token.
• Claude, ChatGPT, Cursor u otra app de IA: normalmente no necesitas ninguna clave. El servidor MCP alojado por Notion te autentica mediante OAuth; nuestra guía de Notion MCP explica cómo configurarlo.

Opción 1: crea un token de acceso personal

Un token de acceso personal (PAT) actúa en tu nombre, con tu condición de miembro del espacio de trabajo y tus permisos sobre las páginas. La propia guía de inicio rápido de la API de Notion empieza con uno, porque no hay nada que configurar aparte del token.

1. Activa el modo de desarrollador. En Notion, abre Configuración, busca Modo de desarrollador y actívalo. Es un ajuste local: debes activarlo tanto en el navegador como en la aplicación de escritorio, y no está disponible en dispositivos móviles.
2. Abre la lista de tokens. Aparecerá una sección para desarrolladores en la barra lateral. Abre Tokens de acceso personal y haz clic en Nuevo token. El enlace directo es notion.so/developers/tokens.
3. Asígnale un nombre y define su alcance. Selecciona la capacidad Notion API (añade Workers solo si despliegas Notion Workers) y un plazo de caducidad: 7, 30, 90 o 180 días, o 1 año, la opción predeterminada. Si aparece un selector de espacios de trabajo, elige el espacio de trabajo: cada token pertenece a un único espacio de trabajo.
4. Haz clic en Crear token y copia su valor de inmediato. Notion lo muestra una sola vez y nunca más, ni siquiera a los administradores. Guárdalo en un gestor de contraseñas o en el almacén de secretos de tu proyecto.

Los nuevos tokens empiezan por ntn_. Notion dejó de usar el prefijo secret_ el 25 de septiembre de 2024, y los tokens antiguos siguen funcionando. Eso sí, no compruebes el prefijo en tu código: Notion indica que el formato puede cambiar y pide a los desarrolladores que traten los tokens como cadenas opacas.

¿No puedes crear un token?

Los invitados y los miembros restringidos no pueden crear PATs en ningún caso. Para los demás, el plan determina quién puede crear uno con acceso a la API de Notion:

En los planes Business y Enterprise, pide a un propietario del espacio de trabajo que lo permita en Configuración → Conexiones. Si más adelante un administrador restringe la política, los tokens que ya tienes dejan de funcionar y devuelven unauthorized.

A qué puede acceder un PAT

Todo lo que puedes abrir en ese espacio de trabajo: páginas, bases de datos, comentarios y archivos. No hace falta compartir las páginas con el token. Eso es lo que hace que los PAT sean rápidos de usar, pero también que la filtración de uno salga cara. La documentación de Notion no describe ningún PAT de solo lectura: la capacidad de la API de Notion permite leer, crear y actualizar. Si una tarea solo necesita leer unas pocas páginas, una conexión interna que solo tenga el permiso Leer contenido es la clave más segura. Cuando pierdes el acceso a una página o abandonas el espacio de trabajo, el token también pierde ese acceso.

Opción 2: crea un token de conexión interna

Una conexión interna es un usuario bot que pertenece a un único espacio de trabajo. Úsala para las automatizaciones de las que depende tu equipo o para cualquier herramienta que deba acceder solo a unas pocas páginas, en lugar de a todo lo que tú puedes abrir. Las guías antiguas la llaman «integración interna», y a su token, «secreto de integración interna» o «token de integración».

1. Comprueba que eres propietario del espacio de trabajo. Solo los propietarios pueden crear conexiones. Si no lo eres, pídeselo a un propietario o crea un espacio de trabajo personal gratuito para hacer pruebas, como sugieren las preguntas frecuentes de Notion.
2. Crea la conexión. En la sección para desarrolladores de la barra lateral, o en notion.so/developers, abre Conexiones internas, haz clic en Crear una nueva conexión, introduce un nombre y elige el espacio de trabajo. Una conexión no se puede trasladar a otro espacio de trabajo más adelante; tendrías que crear una nueva allí.
3. Copia el token de API. Abre la pestaña Configuración de la conexión y copia el Token de API. Los propietarios también pueden acceder a él desde Configuración → Conexiones: el menú ••• junto a la conexión incluye una opción para obtener el token.
4. Configura las capacidades en esa misma pestaña (la lista está más abajo).
5. Dale acceso a páginas. Una conexión nueva no tiene acceso a ningún contenido y todas las solicitudes fallan hasta que compartas algo con ella. En la pestaña Acceso al contenido, haz clic en Editar acceso y selecciona páginas y bases de datos. También puedes abrir una página en Notion, hacer clic en ••• en la esquina superior derecha, buscar Conexiones, elegir Añadir conexión y buscar la tuya. Al compartir una página, también se comparten sus subpáginas.

Las capacidades limitan lo que puede hacer el token, incluso en las páginas a las que tiene acceso. La documentación de Notion recomienda solicitar solo las mínimas necesarias:

• Leer contenido, Actualizar contenido, Insertar contenido, en cualquier combinación. Para exportar, solo se necesita Leer contenido. Un formulario que añade filas solo necesita Insertar contenido. Un script que establece un estado solo necesita Actualizar contenido.
• Leer comentarios, Insertar comentarios.
• Información de usuario: ninguna, sin direcciones de correo electrónico o con direcciones de correo electrónico.

Como la conexión es un usuario independiente, su acceso no depende de las personas. Si la persona del equipo que compartió una página abandona el espacio de trabajo, la conexión conserva el acceso a esa página. Cualquier propietario del espacio de trabajo puede ver todas las conexiones internas, incluidas las que hayan creado otras personas.

Opción 3: OAuth para aplicaciones que usan otras personas

Si estás desarrollando un producto, no pidas a los usuarios que peguen tokens. En su lugar, crea una conexión pública: cada usuario inicia sesión a través de la ventana de OAuth de Notion y elige las páginas que tu aplicación podrá ver. Intercambia el código de OAuth por un token en un servidor que controles. El secreto del cliente nunca debe llegar a un navegador, y los puntos de conexión de tokens de OAuth de Notion bloquean deliberadamente el acceso desde código que se ejecuta en el navegador. IVGraph se conecta de esta forma: eliges las páginas en la ventana de Notion y en ningún momento manejas una clave.

Prueba la clave con una solicitud

Guarda el token en una variable de entorno en lugar de incluirlo en tu código. En macOS o Linux:

export NOTION_API_KEY="ntn_…"

En Windows PowerShell se usa $env:NOTION_API_KEY = "ntn_…". Luego, pregunta a Notion a quién pertenece el token:

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

Si la clave funciona, devuelve un usuario de tipo bot; si se trata de un token de acceso personal, tú eres su propietario. A continuación, comprueba a qué puede acceder la clave. Una búsqueda sin consulta devuelve todas las páginas o fuentes de datos a las que el token tiene acceso. Este filtro conserva solo las fuentes de datos de tus bases de datos, cada una con su propio ID y el ID de la base de datos a la que pertenece:

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

Todas las solicitudes deben incluir el encabezado Notion-Version; 2026-03-11 es la versión más reciente. En JavaScript, el SDK oficial solo necesita que le pases el token una vez y reintenta por ti las solicitudes que exceden el límite de frecuencia. Su versión actual envía 2025-09-03 de forma predeterminada, así que especifica la versión de forma explícita:

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

Dónde encontrar el ID de una página, base de datos o bloque

Cada página, base de datos y bloque de Notion tiene un ID: un UUID de 32 caracteres hexadecimales. Los enlaces lo muestran sin guiones y la API lo acepta con o sin ellos. Con guiones, se agrupa en el formato 8-4-4-4-12, de modo que 1429989fe8ac4effbc8f57f56486db54 pasa a ser 1429989f-e8ac-4eff-bc8f-57f56486db54.

La forma más rápida: modo de desarrollador

Con el modo de desarrollador activado, una barra de desarrollador en la parte inferior de Notion muestra el ID de la página, el bloque, la base de datos o la fuente de datos que estás viendo. Haz clic derecho en un bloque o una base de datos y abre la sección Desarrollador para copiar un ID directamente. Al igual que el propio ajuste, esta función está disponible en el navegador y en la aplicación de escritorio, pero no en dispositivos móviles.

Desde un enlace

Copia el enlace de una página con Compartir → Copiar enlace, o el de un bloque desde su menú ⋮⋮ con Copiar enlace al bloque. Cada tipo de enlace mantiene el ID en una posición fija:

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

Desde junio de 2026, los enlaces a páginas en las respuestas de la API tienen otro formato: https://app.notion.com/p/…. El ID sigue correspondiendo a los últimos 32 caracteres y los enlaces antiguos de notion.so siguen funcionando.

Hay dos casos que suelen generar confusión:

• Bases de datos integradas. Una base de datos integrada está dentro de una página, por lo que la barra de direcciones muestra el ID de esa página. Primero abre la base de datos como página completa y luego copia el enlace.
• Vistas vinculadas. Si el menú de vistas de una base de datos ofrece la opción Abrir base de datos de origen, estás viendo una vista vinculada. La API no puede leer bases de datos vinculadas: abre la base de datos de origen, usa su ID y compártela con tu conexión.

En una base de datos, una propiedad de fórmula con id() muestra el ID de la página de cada fila sin guiones, y id(prop("Project").first()) devuelve el ID de una página relacionada. Esto resulta útil cuando una herramienta de automatización te pide los ID de las filas.

El ID de la fuente de datos, el que no aparece en el enlace

Desde la versión 2025-09-03 de la API, una base de datos es un contenedor de una o varias fuentes de datos. La fuente de datos contiene las propiedades y las filas, por lo que, para consultar filas y crear páginas en una base de datos, se utilizan los puntos de conexión de la ruta /v1/data_sources/. Estos requieren el ID de la fuente de datos, no el ID de la base de datos que aparece en el enlace. Hay tres formas de obtenerlo:

• En Notion: abre el menú de configuración de la base de datos, ve a Gestionar fuentes de datos y haz clic en Copiar ID de la fuente de datos. Si tienes activado el modo de desarrollador, también puedes hacer clic derecho en la base de datos.
• Desde la API: recupera la base de datos y consulta su lista data_sources.
• Desde la búsqueda: el filtro data_source que se muestra arriba.

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

Después, consulta las filas con POST /v1/data_sources/248104cd-477e-80af-bc30-000bd28de8f9/query. Actualmente, la mayoría de las bases de datos tienen una sola fuente de datos, pero no bases tu implementación en ese supuesto. La guía de actualización de Notion advierte que, en cuanto alguien añade una segunda fuente a una base de datos, las conexiones que siguen usando una versión anterior de la API dejan de encontrarla en las búsquedas y sus operaciones de lectura, escritura y consulta en esa base de datos fallan.

En código

El SDK oficial de JavaScript se encarga de este análisis por ti: extractPageId, extractDatabaseId y extractBlockId llegaron en septiembre de 2025. Devuelven el ID con guiones y dan prioridad al ID de la ruta frente a los parámetros de consulta, para que un enlace a una base de datos no te devuelva por error el ID de la vista.

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

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

Soluciona los primeros errores que encontrarás

Las respuestas de error incluyen un código de estado HTTP, un code y un message legible. Estos seis cubren casi todos los problemas del primer día:

Tres problemas más que no parecen errores:

• Las propiedades de tipo Relación aparecen vacías. Comparte también la base de datos relacionada con la conexión. De lo contrario, las propiedades basadas en esa relación no se incluyen en la respuesta. En nuestra guía de relaciones de Notion te explicamos cómo funcionan las relaciones.
• La búsqueda no devuelve resultados. Un token solo encuentra aquello a lo que tiene acceso. En el caso de una conexión, son las páginas que se comparten con ella y sus subpáginas.
• Una solicitud que funcionaba ayer falla hoy. Puede que un PAT haya caducado, que un administrador lo haya revocado o que alguien haya renovado el token de la conexión. Para las conexiones internas y públicas, la pestaña Estado de las herramientas para desarrolladores muestra las solicitudes de las últimas 24 horas con sus códigos de error y las veces que se ha alcanzado el límite de solicitudes.

Límites de frecuencia de solicitudes de la API de Notion en 2026

Notion cambió sus límites el 9 de septiembre de 2026. Las respuestas anteriores describen un límite uniforme de tres solicitudes por segundo de media, con esperas de hasta 15 minutos. Ahora el límite depende del plan y se contabiliza por minuto. Esto es lo que indica la página de Notion sobre los límites de solicitudes:

La cuota por conexión se restablece cada 60 segundos y puede consumirse de una sola vez. Si superas un límite, Notion responde con HTTP 429, el código rate_limited y una cabecera Retry-After con el tiempo de espera en segundos. Para el límite por conexión, esa espera nunca supera los 60 segundos; el límite compartido del espacio de trabajo puede exigir una espera mayor. El campo additional_data.rate_limit_reason indica qué límite has alcanzado. Un error 529 service_overload significa que el propio Notion está saturado: trátalo como un 429. Las llamadas a herramientas de Notion MCP consumen las mismas cuotas.

Cómo mantenerte dentro de ellos:

1. Envía las solicitudes a través de una sola cola, no mediante procesos en paralelo que reintenten cada uno por su cuenta.
2. Si recibes un error 429 o 529, espera el tiempo indicado en Retry-After y vuelve a intentarlo. Si vuelve a ocurrir, aumenta exponencialmente el tiempo de espera con una pequeña variación aleatoria y limita el número de intentos.
3. No reintentes la mayoría de las solicitudes que devuelvan errores 400: corrige la solicitud. Un error 429 con el motivo public_api_request_blocked tampoco se resolverá esperando; contacta con el soporte de Notion.
4. Antes de repetir una operación de escritura que haya devuelto un error 503, lee additional_data.retry_guidance. Puede que el cambio ya se haya guardado y, si lo repites, se aplicaría dos veces.

Mantén la clave a salvo

Cualquiera que tenga el token puede hacer todo lo que este permita. En el caso de un PAT, eso incluye todo lo que puedes abrir; en el de una conexión, todas las páginas compartidas con ella.

• Guárdalo fuera de tu código: en una variable de entorno para el trabajo local, con .env incluido en .gitignore, y en un gestor de secretos en producción.
• Nunca lo incluyas en una página web. La API de Notion acepta solicitudes desde código ejecutado en el navegador, por lo que cualquier persona que consulte el código fuente de una página accesible para otros puede usar un token incrustado en ella.
• No lo pegues en chats, solicitudes de soporte ni sistemas de seguimiento de incidencias, incluidas las conversaciones con asistentes de IA.
• Usa un token por herramienta y por entorno, para que revocar uno no afecte al funcionamiento de los demás.
• Concede los permisos mínimos. Para una herramienta de terceros, una conexión interna que solo tenga acceso a las páginas que compartes es más segura que un PAT que tenga acceso a todo lo que tú puedes ver. Configura un plazo de caducidad corto para los PAT experimentales.
• Activa la detección de secretos en tu repositorio y en tu CI. El prefijo ntn_ existe para que los escáneres puedan reconocer los tokens de Notion.

Si se filtra un token, sigue estos pasos en este orden. En Notion, abre Configuración → Conexiones → Desarrollar o gestionar conexiones, busca la conexión o el token y haz clic en Actualizar si se trata de una conexión interna, o revoca el PAT. Sustituye el valor anterior en todos los lugares donde se haya usado. Después, revisa los cambios recientes en tus páginas y bases de datos y busca conexiones que no reconozcas. Los administradores del espacio de trabajo también pueden revocar el PAT de cualquier miembro desde Configuración → Conexiones, aunque nunca pueden ver ni copiar el token en sí.

Cuándo no necesitas una clave de API

• Apps de IA. Claude, ChatGPT, Cursor, Codex y VS Code se conectan al servidor MCP alojado por Notion mediante OAuth, por lo que no tienes que crear ninguna clave. Nuestro asistente de configuración de MCP para Notion te da la configuración exacta para cada app. Hay dos excepciones: en los planes Business y Enterprise, un propietario del espacio de trabajo puede crear un token MCP para clientes que no pueden abrir una ventana de inicio de sesión; por su parte, el servidor MCP de código abierto y autoalojado utiliza un token de API, aunque Notion ya no lo mantiene activamente.
• Apps que usan el inicio de sesión de Notion. Una herramienta que abre la ventana de Notion y te pide que elijas páginas utiliza una conexión pública, y tú nunca ves ningún token.
• Visualiza las conexiones de tu espacio de trabajo. Es habitual recopilar los ID de páginas y bases de datos para trazar las relaciones a mano. IVGraph se conecta a través de la ventana de OAuth de Notion y representa cada página, mención y relación de base de datos en un grafo 3D interactivo. Es gratis hasta 500 nodos.

Si un agente debe leer ese grafo, IVGraph ofrece una API para agentes de solo lectura con su propio token de servicio en los planes Pro y Max: búsqueda, contenido de páginas, vecinos y rutas entre páginas. Aún no hay un servidor MCP de IVGraph.

Preguntas frecuentes