Como obter uma chave de API do Notion e encontrar os IDs necessários para suas requisições

Uma chave de API do Notion é o token que seu código envia em cada requisição à API do Notion. Em 2026, existem três tipos: um token de acesso pessoal que age em seu nome, um token de conexão interna para automações da equipe e OAuth para aplicativos que outras pessoas instalam. A seguir, veja como criar cada um deles, conceder acesso às suas páginas, encontrar os IDs de página, banco de dados e fonte de dados necessários para suas requisições e corrigir os erros que quase todo mundo encontra na primeira tentativa.

De qual chave de API do Notion você precisa?

A documentação para desenvolvedores do Notion lista três formas de autenticação. Elas diferem quanto a quem pertencem as permissões associadas ao token, ao que ele pode visualizar e a quem tem permissão para criá-lo.

Um jeito rápido de escolher:

• Um script, notebook ou ferramenta que só você usa: um token de acesso pessoal. Nada para compartilhar, tudo funcionando em dois minutos.
• Uma automação da qual a equipe depende: uma conexão interna. Ela continua funcionando mesmo depois que a pessoa que a configurou sai e só tem acesso às páginas que você compartilha com ela.
• Um app que outras pessoas instalam: uma conexão pública com OAuth. Nunca peça aos seus usuários que colem um token.
• Claude, ChatGPT, Cursor ou outro app de IA: geralmente, nenhuma chave é necessária. O servidor MCP hospedado pelo Notion autentica você com OAuth; nosso guia do Notion MCP explica a configuração.

Opção 1: crie um token de acesso pessoal

Um token de acesso pessoal (PAT) atua em seu nome, com seu vínculo ao espaço de trabalho e suas permissões de página. O próprio guia de início rápido da API do Notion começa com um, porque não há nada para configurar além do token.

1. Ative o Modo de desenvolvedor. No Notion, abra Configurações, busque por Modo de desenvolvedor e ative a opção. É uma configuração local: você precisa ativá-la tanto no navegador quanto no aplicativo para desktop, e ela não está disponível em dispositivos móveis.
2. Abra a lista de tokens. Uma seção para desenvolvedores aparece na barra lateral. Abra Tokens de acesso pessoal e clique em Novo token. O link direto é notion.so/developers/tokens.
3. Dê um nome ao token e defina seu escopo. Selecione o recurso API do Notion (adicione Workers somente se você implantar Notion Workers) e um prazo de validade: 7, 30, 90 ou 180 dias, ou 1 ano, que é o padrão. Se aparecer um seletor de espaço de trabalho, escolha o espaço de trabalho: cada token pertence a um único espaço de trabalho.
4. Clique em Criar token e copie o valor imediatamente. O Notion só o exibe uma vez e nunca mais, nem mesmo para administradores. Guarde-o em um gerenciador de senhas ou no repositório de segredos do seu projeto.

Os novos tokens começam com ntn_. O Notion deixou de usar o prefixo secret_ em 25 de setembro de 2024, e os tokens antigos continuam funcionando. Mas não verifique o prefixo no seu código: o Notion informa que o formato pode mudar e pede que os desenvolvedores tratem os tokens como strings opacas.

Não consegue criar um token?

Convidados e membros com acesso restrito não podem criar PATs de forma alguma. Para os demais, o plano define quem pode criar um PAT com acesso à API do Notion:

Nos planos Business e Enterprise, peça a um proprietário do espaço de trabalho para permitir a conexão em Configurações → Conexões. Se um administrador restringir a política depois, os tokens que você já tem deixarão de funcionar e retornarão unauthorized.

O que um PAT pode acessar

Tudo o que você pode abrir nesse espaço de trabalho: páginas, bancos de dados, comentários e arquivos. Não é preciso compartilhar as páginas com o token. É isso que torna os PATs rápidos de usar e também o que faz um vazamento de PAT sair caro. A documentação do Notion não descreve nenhum PAT somente de leitura: a permissão de acesso à API do Notion permite ler, criar e atualizar. Se uma tarefa só precisa ler algumas páginas, uma conexão interna com apenas a permissão Ler conteúdo é a chave mais segura. Quando você perde acesso a uma página ou sai do espaço de trabalho, o token também perde esse acesso.

Opção 2: crie um token de conexão interna

Uma conexão interna é um usuário bot que pertence a um único espaço de trabalho. Use-a em automações das quais a equipe depende ou em qualquer ferramenta que deva ter acesso a poucas páginas, em vez de tudo o que você pode abrir. Guias mais antigos a chamam de “integração interna”, e seu token, de “segredo da integração interna” ou “token de integração”.

1. Confira se você é proprietário do espaço de trabalho. Só proprietários podem criar conexões. Se você não for, peça a um proprietário ou crie um espaço de trabalho pessoal gratuito para fazer testes, como sugerem as perguntas frequentes do Notion.
2. Crie a conexão. Na seção de desenvolvedores da barra lateral ou em notion.so/developers, abra Conexões internas, clique em Criar uma nova conexão, digite um nome e escolha o espaço de trabalho. Não é possível transferir uma conexão para outro espaço de trabalho depois; você precisaria criar uma nova lá.
3. Copie o token de API. Abra a aba Configuração da conexão e copie o token de API. Proprietários também podem acessá-lo em Configurações → Conexões: o menu ••• ao lado da conexão tem uma opção para recuperar o token.
4. Defina os recursos na mesma aba (a lista está abaixo).
5. Conceda acesso às páginas. Uma conexão nova não consegue ver nada, e todas as solicitações falham até que você compartilhe algum conteúdo. Na aba Acesso ao conteúdo, clique em Editar acesso e selecione páginas e bancos de dados. Ou abra uma página no Notion, clique em ••• no canto superior direito, encontre Conexões, escolha Adicionar conexão e busque a sua. Compartilhar uma página também compartilha suas subpáginas.

As permissões limitam o que o token pode fazer, mesmo nas páginas que ele pode visualizar. A documentação do Notion recomenda solicitar apenas o mínimo necessário:

• Ler conteúdo, Atualizar conteúdo, Inserir conteúdo, em qualquer combinação. Uma exportação precisa apenas de Ler conteúdo. Um formulário que adiciona linhas precisa apenas de Inserir conteúdo. Um script que define um status precisa apenas de Atualizar conteúdo.
• Ler comentários, Inserir comentários.
• Informações do usuário: nenhuma, sem endereços de e-mail ou com endereços de e-mail.

Como a própria conexão é um usuário, seu acesso não depende de pessoas. Se a pessoa da equipe que compartilhou uma página sair do espaço de trabalho, a conexão mantém o acesso a essa página. Todos os proprietários do espaço de trabalho podem ver todas as conexões internas, inclusive as criadas por outras pessoas.

Opção 3: OAuth para apps usados por outras pessoas

Se você está criando um produto, não peça aos usuários que colem tokens. Em vez disso, crie uma conexão pública: cada usuário faz login pela janela OAuth do Notion e escolhe as páginas que seu app pode visualizar. Troque o código OAuth por um token em um servidor que você controla. O segredo do cliente nunca deve chegar a um navegador, e os endpoints de token OAuth do Notion são deliberadamente bloqueados para código executado no navegador. O IVGraph se conecta assim: você escolhe as páginas na janela do Notion e nunca lida com uma chave.

Teste a chave com uma solicitação

Guarde o token em uma variável de ambiente, não no seu código. No macOS ou Linux:

export NOTION_API_KEY="ntn_…"

No Windows PowerShell, use $env:NOTION_API_KEY = "ntn_…". Depois, pergunte ao Notion a quem o token pertence:

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

Uma chave válida retorna um usuário do tipo bot; no caso de um token de acesso pessoal, o proprietário é você. Em seguida, veja o que a chave pode acessar. Uma busca sem um termo de pesquisa retorna todas as páginas ou fontes de dados que o token pode acessar. Este filtro mantém apenas as fontes de dados dos seus bancos de dados, cada uma com seu próprio ID e o ID do banco de dados ao qual pertence:

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

Toda requisição precisa do cabeçalho Notion-Version; 2026-03-11 é a versão mais recente. Em JavaScript, o SDK oficial recebe o token uma única vez e refaz automaticamente as requisições afetadas pela limitação de taxa. A versão atual do SDK envia 2025-09-03 por padrão, então defina a versão explicitamente:

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

Onde encontrar o ID de uma página, banco de dados ou bloco

Cada página, banco de dados e bloco no Notion tem um ID: um UUID de 32 caracteres hexadecimais. Os links exibem esse ID sem hífens, e a API o aceita com ou sem eles. Com hífens, ele é agrupado no formato 8-4-4-4-12, então 1429989fe8ac4effbc8f57f56486db54 fica 1429989f-e8ac-4eff-bc8f-57f56486db54.

O jeito mais rápido: Modo de desenvolvedor

Com o Modo de desenvolvedor ativado, uma barra de desenvolvedor na parte inferior do Notion mostra o ID da página, do bloco, do banco de dados ou da fonte de dados que você está visualizando. Clique com o botão direito em um bloco ou banco de dados e abra a seção Desenvolvedor para copiar um ID diretamente. Assim como a própria configuração, esse recurso funciona no navegador e no aplicativo para computador, mas não em dispositivos móveis.

A partir de um link

Copie o link de uma página em Compartilhar → Copiar link, ou o link de um bloco pelo menu ⋮⋮, em Copiar link do bloco. Cada tipo de link mantém o ID em uma posição fixa:

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 junho de 2026, os links de páginas nas respostas da API usam outro formato, https://app.notion.com/p/…. O ID ainda corresponde aos últimos 32 caracteres, e os links antigos do notion.so continuam funcionando.

Dois casos costumam causar confusão:

• Bancos de dados em linha. Um banco de dados em linha fica dentro de uma página, então a barra de endereço mostra o ID da página. Primeiro, abra o banco de dados como página inteira e depois copie o link.
• Visualizações vinculadas. Se o menu de visualizações de um banco de dados oferecer a opção Abrir banco de dados de origem, você está em uma visualização vinculada. A API não consegue ler bancos de dados vinculados: abra o banco de dados de origem, use o ID dele e compartilhe-o com sua conexão.

Em um banco de dados, uma propriedade de fórmula com id() mostra o ID da página de cada linha sem hífens, e id(prop("Project").first()) retorna o ID de uma página relacionada. Isso ajuda quando uma ferramenta de automação pede os IDs das linhas.

O ID da fonte de dados, aquele que não está no link

Desde a versão 2025-09-03 da API, um banco de dados é um contêiner para uma ou mais fontes de dados. A fonte de dados armazena as propriedades e as linhas, então a consulta de linhas e a criação de páginas em um banco de dados são feitas por meio de endpoints em /v1/data_sources/. Esses endpoints recebem o ID da fonte de dados, não o ID do banco de dados que aparece no link. Há três maneiras de obter esse ID:

• No Notion: abra o menu de configurações do banco de dados, vá até Gerenciar fontes de dados e clique em Copiar ID da fonte de dados. Com o Modo de desenvolvedor ativado, clicar com o botão direito no banco de dados também funciona.
• Pela API: recupere o banco de dados e leia a lista data_sources dele.
• Pela busca: o filtro data_source mostrado acima.

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

Depois, consulte as linhas com POST /v1/data_sources/248104cd-477e-80af-bc30-000bd28de8f9/query. Hoje, a maioria dos bancos de dados tem uma única fonte de dados, mas não se baseie nisso ao desenvolver. O guia de atualização do Notion alerta que, assim que alguém adiciona uma segunda fonte a um banco de dados, as conexões que ainda usam uma versão anterior da API deixam de encontrá-lo na busca, e as operações de leitura, gravação e consulta nesse banco de dados falham.

No código

O SDK oficial de JavaScript faz essa análise para você: extractPageId, extractDatabaseId e extractBlockId chegaram em setembro de 2025. Eles retornam o ID com hífens e dão preferência ao ID no caminho em vez dos parâmetros de consulta, para que um link para um banco de dados não retorne o ID da visualização por engano.

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

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

Corrija os primeiros erros que você vai encontrar

As respostas de erro incluem um status HTTP, um code e uma message legível. Estes seis abrangem quase todos os problemas que surgem no primeiro dia:

Mais três problemas que não parecem erros:

• As propriedades de Relação retornam vazias. Compartilhe também o banco de dados relacionado com a conexão. Caso contrário, as propriedades baseadas nessa relação ficam de fora da resposta. Nosso guia de relações do Notion explica como as relações funcionam.
• A busca não retorna resultados. Um token só encontra o que pode acessar. No caso de uma conexão, são as páginas compartilhadas com ela e suas subpáginas.
• Uma solicitação que funcionava ontem falha hoje. Um PAT pode ter expirado, um administrador pode tê-lo revogado ou alguém pode ter renovado o token da conexão. Para conexões internas e públicas, a aba Integridade nas ferramentas para desenvolvedores lista as solicitações das últimas 24 horas com seus códigos de erro e as ocorrências em que o limite de solicitações foi atingido.

Limites de requisições da API do Notion em 2026

O Notion alterou seus limites em 9 de setembro de 2026. Respostas mais antigas descrevem uma média fixa de três solicitações por segundo, com esperas de até 15 minutos. Agora, o limite depende do plano e é contabilizado por minuto. Veja o que diz a página de limites de solicitações do Notion:

A cota por conexão é renovada a cada 60 segundos e pode ser consumida de uma só vez. Ao ultrapassar um limite, o Notion responde com HTTP 429, o código rate_limited e um cabeçalho Retry-After em segundos. Para o limite por conexão, essa espera nunca ultrapassa 60 segundos; já o limite compartilhado do espaço de trabalho pode exigir uma espera maior. O campo additional_data.rate_limit_reason informa qual limite você atingiu. Um erro 529 service_overload significa que o próprio Notion está sobrecarregado: trate-o como um 429. As chamadas às ferramentas do Notion MCP consomem as mesmas cotas.

Como se manter dentro deles:

1. Envie as requisições por uma única fila, não por processos paralelos que fazem novas tentativas por conta própria.
2. Ao receber 429 ou 529, aguarde o tempo indicado em Retry-After e tente novamente. Se acontecer de novo, aumente exponencialmente o intervalo entre as tentativas, com uma pequena variação aleatória, e limite o número de tentativas.
3. Na maioria dos erros 400, não tente novamente: corrija a requisição. Um 429 com o motivo public_api_request_blocked também não se resolve esperando; entre em contato com o suporte do Notion.
4. Antes de repetir uma operação de escrita que retornou 503, leia additional_data.retry_guidance. A alteração pode já ter sido salva, e repeti-la faria com que fosse aplicada duas vezes.

Mantenha a chave segura

Qualquer pessoa com o token pode fazer tudo o que ele permite. No caso de um PAT, isso inclui tudo o que você pode abrir; no caso de uma conexão, todas as páginas compartilhadas com ela.

• Armazene o token fora do código: em uma variável de ambiente para o trabalho local, com .env listado em .gitignore, e em um gerenciador de segredos em produção.
• Nunca coloque o token em uma página da web. A API do Notion aceita requisições feitas por código executado no navegador, então um token incorporado a uma página que outras pessoas podem abrir pode ser usado por qualquer pessoa que visualize seu código-fonte.
• Não cole o token em chats, chamados de suporte ou sistemas de rastreamento de problemas, e isso inclui conversas com assistentes de IA.
• Use um token por ferramenta e por ambiente, para que revogar um não comprometa o funcionamento dos demais.
• Conceda apenas o mínimo necessário. Para uma ferramenta de terceiros, uma conexão interna que acessa apenas as páginas que você compartilha é mais segura do que um PAT que acessa tudo o que você pode acessar. Defina um prazo de expiração curto para PATs experimentais.
• Ative a detecção de segredos no seu repositório e na CI. O prefixo ntn_ existe para que as ferramentas de detecção possam reconhecer tokens do Notion.

Se um token vazar, siga esta ordem. No Notion, abra Configurações → Conexões → Desenvolver ou gerenciar conexões, encontre a conexão ou o token e clique em Atualizar no caso de uma conexão interna ou revogue o PAT. Substitua o valor antigo em todos os lugares onde ele foi usado. Depois, verifique as alterações recentes nas suas páginas e bancos de dados e procure conexões que você não reconhece. Administradores do espaço de trabalho também podem revogar o PAT de qualquer membro em Configurações → Conexões, mas nunca podem ver nem copiar o token em si.

Quando você não precisa de uma chave de API

• Apps de IA. Claude, ChatGPT, Cursor, Codex e VS Code se conectam ao servidor MCP hospedado pelo Notion via OAuth, então você não precisa criar nenhuma chave. Nosso assistente de configuração do MCP do Notion fornece a configuração exata para cada app. Há duas exceções: nos planos Business e Enterprise, um proprietário do espaço de trabalho pode criar um token MCP para clientes que não conseguem abrir uma janela de login, e o servidor MCP de código aberto e hospedado por conta própria usa um token de API, embora o Notion não faça mais a manutenção ativa desse servidor.
• Apps que usam o login do Notion. Uma ferramenta que abre a janela do Notion e pede que você escolha páginas usa uma conexão pública, e você nunca vê um token.
• Veja como seu espaço de trabalho se conecta. É comum coletar IDs de páginas e bancos de dados para mapear relações manualmente. O IVGraph se conecta pela janela de OAuth do Notion e representa cada página, menção e relação de banco de dados em um grafo 3D interativo. É gratuito para até 500 nós.

Se um agente precisar ler esse grafo, o IVGraph oferece uma API para agentes somente de leitura, com seu próprio token de serviço nos planos Pro e Max: busca, conteúdo de páginas, vizinhos e caminhos entre páginas. Ainda não há um servidor MCP do IVGraph.

Perguntas frequentes