Autenticação de API é onde mais gente trava no n8n, e quase sempre por um motivo simples: escolher o tipo errado. São basicamente quatro formas — chave em cabeçalho, chave em parâmetro, Bearer token e OAuth2 —, e a documentação da API diz qual usar, ainda que nem sempre com essas palavras. Este texto traduz o que a documentação fala para o que você seleciona no node.
Adicione ao Google NotíciasNeste artigo
As quatro formas, e como reconhecer cada uma
| Se a documentação diz | É | Onde vai |
|---|---|---|
"Include your API key in the X-API-Key header" | Chave em cabeçalho | Cabeçalho com o nome indicado |
"Add ?api_key= to the URL" | Chave em parâmetro | Parâmetro de consulta |
| "Authorization: Bearer <token>" | Bearer token | Cabeçalho Authorization |
| "Authorize the application" | OAuth2 | Fluxo de autorização |
Chave em cabeçalho
A mais comum em APIs modernas. Você recebe uma chave longa e ela vai num cabeçalho cujo nome a API define — X-API-Key, apikey, Api-Token, varia.
No n8n, isso é uma credencial de autenticação por cabeçalho genérico: você informa o nome do cabeçalho e o valor. Simples, e o erro típico é digitar o nome errado — a API responde 401 sem dizer que o problema é o nome, não o valor.
Chave em parâmetro de consulta
Formato mais antigo, ainda comum em APIs públicas. A chave vai na própria URL, como parâmetro.
Chave em URL aparece em log de servidor, em histórico de proxy e no registro de execução. Não é o formato mais seguro, e quando a API oferecer as duas opções, prefira o cabeçalho. Quando só oferecer parâmetro, evite deixar o histórico de execuções guardando essas requisições por muito tempo.
Bearer token
Variação padronizada da chave em cabeçalho: sempre no cabeçalho Authorization, sempre com a palavra Bearer antes do valor.
O erro clássico aqui é colar o token já com a palavra Bearer incluída, quando o campo espera só o token — o resultado vira Bearer Bearer abc123, e a API recusa. Se a autenticação falha e você tem certeza de que o token está certo, verifique isso primeiro.
OAuth2
É o mais complexo e o mais seguro, usado quando a API dá acesso a dados de outra pessoa — sua conta do Google, do Slack, do sistema do cliente.
Em vez de uma chave fixa, existe um fluxo: você registra a aplicação no serviço, recebe um identificador e um segredo, autoriza o acesso pelo navegador e o serviço devolve um token temporário que se renova sozinho.
O que costuma dar errado:
URL de redirecionamento diferente. O endereço que você cadastrou no serviço precisa ser exatamente o que o n8n mostra. Uma barra a mais reprova.
Escopos insuficientes. Você autorizou leitura e o fluxo tenta escrever. A resposta é 403, e a solução é refazer a autorização com os escopos certos.
Autorização revogada. Trocar a senha da conta costuma derrubar as autorizações. O fluxo funcionava e parou sozinho — reconecte.
Onde as credenciais ficam
Credenciais são cadastradas separadamente dos fluxos e armazenadas de forma criptografada. Os fluxos apenas fazem referência a elas — quem abre o fluxo não vê o valor.
Duas consequências práticas:
Reutilize. Cadastre a conexão com um serviço uma vez e use em todos os fluxos. Ter cinco credenciais do mesmo serviço significa cinco lugares para atualizar quando a chave mudar.
Separe por permissão. Quando o serviço permitir, crie chaves diferentes com o mínimo de acesso necessário para cada uso. Uma credencial que só precisa ler não deveria poder apagar.
Um roteiro para quando falhar
É 401 ou 403? 401 é a credencial; 403 é permissão. Não confunda os dois ou vai procurar no lugar errado.
O nome do cabeçalho está exato? Diferencia maiúsculas em algumas APIs.
Há espaço ou quebra de linha no valor? Colar de e-mail costuma trazer lixo invisível junto.
O token expirou? Alguns têm validade curta e precisam ser renovados.
Funciona fora do n8n? Testar a mesma requisição por fora separa "credencial errada" de "configuração errada no node".
Identifique o tipo pela documentação, cadastre a credencial uma vez, reutilize em todos os fluxos e, ao falhar, comece perguntando se é 401 ou 403.
Perguntas frequentes
Como autenticar uma API no n8n?
Identificando o tipo na documentação da API e cadastrando a credencial correspondente: chave em cabeçalho, chave em parâmetro de consulta, Bearer token ou OAuth2. A credencial é cadastrada uma vez e reutilizada em quantos fluxos precisar.
Qual a diferença entre API key e OAuth2?
A chave de API é um valor fixo que identifica você e não expira sozinha. O OAuth2 é um fluxo de autorização usado quando a API dá acesso a dados de uma conta específica: envolve autorizar pelo navegador e gera um token temporário que se renova automaticamente.
Por que minha autenticação Bearer falha mesmo com o token certo?
Uma causa muito frequente é colar o token já incluindo a palavra "Bearer", quando o campo espera apenas o valor. O resultado é a palavra duplicada no cabeçalho, e a API recusa. Vale conferir também espaços ou quebras de linha coladas junto.
Minha integração OAuth2 parou de funcionar sozinha. Por quê?
Normalmente porque a autorização foi revogada — trocar a senha da conta costuma derrubar os acessos concedidos. Também acontece quando os escopos autorizados não cobrem a operação que o fluxo tenta fazer, o que gera erro de permissão.
As credenciais ficam visíveis nos fluxos?
Não. Elas são cadastradas separadamente e armazenadas criptografadas; os fluxos apenas as referenciam. Quem visualiza um fluxo não enxerga o valor da chave ou do token.
