BLOG
OAuth2 no n8n permite que um workflow acesse um serviço externo usando uma credencial autorizada, quando o provedor oferece esse mecanismo. A configuração depende do grant aceito pelo serviço, das URLs de autorização e token, do client ID, do client secret, do redirect e dos scopes. Não há valores universais: copie os dados do provedor e da credencial exibida pelo n8n. A API pública do próprio n8n usa API key, portanto não confunda esse caso com OAuth2 de uma API externa.
Para ver outro caso que usa a API pública do n8n — com chave de API, não OAuth2 — consulte como criar um rascunho WordPress com n8n pela API.
Nota editorial: análise baseada nas fontes oficiais vinculadas e no Planejador Google; não houve teste próprio. Preços, acesso, limites e funcionalidades podem mudar e devem ser confirmados no serviço antes da implantação.
OAuth2: autorização delegada no n8n
No fluxo mais comum de authorization code, a pessoa aprova o acesso em uma página do provedor; o cliente recebe um código e troca por tokens. Client credentials é voltado a comunicação máquina a máquina quando o provedor o suporta. A documentação do n8n para credenciais do HTTP Request descreve opções de OAuth2, mas a escolha correta depende do serviço alvo. Não escolha o grant só porque parece mais fácil: o provedor pode não suportá-lo para o tipo de conta ou recurso.
OAuth não é uma senha e não deve ser digitado no prompt nem armazenado em texto. O client secret identifica o cliente e deve ficar guardado como segredo. O access token autoriza chamadas por um período; o refresh token pode permitir renovação quando fornecido e habilitado pelo provedor. Prazos, rotação e revogação variam. Leia a política do serviço e teste o ciclo de vida real da credencial, em vez de assumir que ficará ativa indefinidamente.
Referência: n8n HTTP Request credentials.
Antes de configurar, reúna dados do provedor
Confirme se a API está habilitada, qual URL de autorização e token se aplica ao ambiente, quais escopos são necessários e se há exigência de aprovação de administrador. Copie o redirect URI mostrado pela credencial n8n sem alterar protocolo, porta ou barra final. Cadastre esse endereço no console do provedor; divergência de um caractere causa erro de redirect mismatch. Em staging, use as URLs de teste quando oferecidas.
Crie um client OAuth dedicado ao workflow, não reutilize o app de produção de outro sistema. Limite scopes ao endpoint e à operação necessários. Se o provedor exige consentimento ou verificação de aplicativo, planeje essa etapa e não procure um caminho alternativo que contorne a política. Registre nome do projeto, owner, data de expiração e como revogar o acesso, mas nunca registre o segredo ou token nos arquivos de documentação.
Referência: n8n credential types.
Configure a credencial no n8n
No tipo de credencial do HTTP Request, selecione OAuth2 e preencha os campos conforme a documentação do provedor. Para authorization code, verifique URL de autorização, URL do token, client ID, client secret, escopos e método de autenticação de cliente esperado. Para client credentials, confirme se há endpoint e escopos apropriados. O n8n pode oferecer credencial predefinida para o serviço; quando existir, ela tende a reduzir campos e erros de configuração.
Salve a credencial e complete a autorização usando uma conta de teste. A tela de consentimento deve mostrar a aplicação correta e escopos compatíveis com a tarefa. Se aparecer acesso amplo a arquivos, contatos ou administração, pare e revise o escopo. Após a autorização, confira se o teste envia a chamada esperada e se o n8n mascara tokens. Não envie capturas com dados de conta ou segredo para suporte público.
Referência: n8n API authentication.
Faça uma chamada mínima e identifique erros
Use endpoint de leitura e um registro não sensível. Uma resposta 401 pode sinalizar token ausente, expirado ou enviado no formato errado; 403 indica que a identidade foi autenticada, mas não tem permissão; 400 geralmente aponta parâmetro ou corpo inválido. `invalid_grant`, redirect mismatch e consentimento ainda não aprovado são problemas distintos. Guarde o código e a mensagem sanitizada, mas retire tokens, client secret e dados pessoais antes de abrir chamado.
Teste ao menos um token expirado ou revogado em ambiente controlado, e confirme se a credencial pede nova autorização ou renova automaticamente. Não suponha que refresh token existe; alguns provedores não emitem, expiram, rotacionam ou exigem parâmetros offline. A rotina precisa lidar com falha de refresh e alertar responsável sem repetir escritas. Se o provedor rotaciona refresh token, verifique que o cliente atualiza o valor armazenado.
Referência: n8n HTTP Request credentials.
Separe OAuth do uso da API pública do n8n
Se o objetivo é chamar o n8n API — por exemplo, inventariar workflows — a referência oficial descreve API key em `X-N8N-API-KEY`, não credencial OAuth2. Essa chave pode ter alcance administrativo, conforme edição e escopos disponíveis. Para integrar n8n a um serviço externo com OAuth, use a credencial específica desse serviço. Confundir as duas integrações gera configuração incompatível e aumenta risco de credenciais privilegiadas em nodes desnecessários.
Faça um diagrama simples com sistema cliente, n8n, serviço de autorização e API alvo. Marque quem emite access token, onde fica client secret e em qual chamada entra cada token. Se o fluxo inicia no n8n e fala com Google ou CRM, o segredo pertence à credencial do serviço externo. Se outro sistema chama a API administrativa do n8n, aplique a autenticação que a documentação da API requer. Nunca compartilhe tokens entre os dois caminhos.
Referência: n8n credential types.
Armazenamento, compartilhamento e rotação
Restrinja quem pode editar e usar a credencial no n8n. O acesso ao workflow não deve automaticamente permitir exportar ou visualizar segredos. Use projetos/roles conforme o plano e a edição, e mantenha diferentes credenciais para desenvolvimento e produção. Ao trocar de responsável ou suspeitar de vazamento, revogue no provedor e substitua no n8n; apagar o valor de um node não revoga um token ainda válido no serviço.
Estabeleça calendário de revisão e acompanhe falhas de autenticação. Rotação frequente sem coordenação também pode derrubar processos; combine emissão, validação e revogação em uma janela controlada. Revise logs de execuções, exports e backups. Não deixe o access token em dados pinados, exemplos, documentação de operação ou logs do proxy. Se precisar investigar, use IDs de execução e mensagens sanitizadas, não valores de autorização.
Referência: n8n API authentication.
Checklist de produção
Confirme: grant suportado; redirect registrado exatamente; scopes mínimos; consentimento apropriado; teste de leitura; chamada negada sem escopo; expiração e refresh conhecidos; notificação de falha; segredo protegido; usuário responsável; plano de revogação; credenciais separadas por ambiente. Depois teste uma operação de escrita com registro fictício ou recurso reversível, faça rollback e confira os logs sanitizados.
Uma autenticação bem-sucedida não garante que o fluxo está pronto para produção. A autorização pode vencer, a política de API mudar ou o usuário perder acesso. Monitore respostas de token e estabeleça alerta que não exponha dados. Se o serviço exigir OAuth app review ou permissão administrativa, trate a aprovação como requisito formal. Para operações críticas, documente um caminho manual e não dependa de reautorização em uma conta pessoal indisponível.
Referência: n8n HTTP Request credentials.
Perguntas frequentes
OAuth2 é igual a API key?
Não. OAuth2 delega acesso por tokens e grants; uma API key é uma credencial estática ou gerenciada de forma diferente pelo serviço.
Posso usar qualquer grant no n8n?
Use apenas o grant aceito pelo provedor e compatível com a credencial configurada.
O n8n renova sempre o token?
Depende dos tokens e regras do provedor. Confirme emissão, expiração, rotação e revogação.
Qual URL de callback devo cadastrar?
A URL de redirect exibida pela credencial n8n, copiada exatamente para o console do provedor.
A API pública do n8n usa OAuth2?
A documentação atual da API pública usa API key no cabeçalho `X-N8N-API-KEY`.
Fontes principais: n8n HTTP Request credentials; n8n credential types; n8n API authentication.
