OAuth2 / n8n

Autenticação via OAuth2 client_credentials para automações com n8n, Zapier, Make ou scripts próprios.

Quando usar OAuth2 em vez de API Key

A API Externa v2 (/api/external/v2/**) usa OAuth2 client_credentials com escopos granulares. Cada cliente OAuth2 recebe apenas os escopos que precisa — útil para limitar o que cada automação pode fazer sem entregar a credencial mestre da aplicação.

A API Key + Secret (v2 clássica, em /api/external/**) continua disponível para integrações simples. OAuth2 é recomendado quando você precisa de escopos granulares por automação ou quando integra via n8n/Zapier.

Obtenção do Token

POST

/oauth2/token

Content-Type: application/x-www-form-urlencoded

Parâmetro	Tipo	Descrição
`grant_type`	string	Sempre `client_credentials`
`client_id`	string	Identificador do cliente OAuth2 (fornecido pelo painel admin)
`client_secret`	string	Segredo do cliente OAuth2 (exibido uma única vez na criação)
`scope`	string	Escopos solicitados, separados por espaço (ver tabela abaixo)

Exemplo (curl)

curl -X POST https://api.avizuai.com.br/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=app-minha-empresa-scheduler" \
  -d "client_secret=<secret>" \
  -d "scope=mensagens:enviar atendimentos:read"

Resposta de Sucesso

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mensagens:enviar atendimentos:read"
}

O access_token é um JWT RS256 com o claim aplicacao_id — o servidor identifica automaticamente a aplicação destino a partir dele.

Escopos disponíveis

Escopo	Permite	Endpoints (exemplos)
`mensagens:enviar`	Enviar mensagens WhatsApp	`POST /api/external/v2/mensagens`
`atendimentos:read`	Listar fila e atendimentos em andamento	`GET /api/external/v2/atendimentos/fila` `GET /api/external/v2/atendimentos/em-andamento`
`atendimentos:escalar`	Forçar escalação de sessão para humano	`POST /api/external/v2/atendimentos/{id}/escalar`
`agendamentos:read`	Consultar agendamentos de saúde	`GET /api/external/v2/agendamentos`
`agendamentos:write`	Criar e atualizar agendamentos	`POST /api/external/v2/agendamentos` `PATCH /api/external/v2/agendamentos/{id}`
`pacientes:read`	Consultar cadastro de pacientes	`GET /api/external/v2/pacientes`
`pacientes:write`	Criar e atualizar pacientes	`POST /api/external/v2/pacientes`

Solicite no scope apenas os escopos que sua automação realmente usa. O cliente OAuth2 só recebe o que foi autorizado durante o cadastro no painel admin.

Uso do Token

Inclua o token retornado no header Authorization das chamadas à API:

curl -X POST https://api.avizuai.com.br/api/external/v2/mensagens \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"telefone":"+5511999998888","mensagem":"Oi"}'

Integração com n8n

No n8n, configure um nó HTTP Request com autenticação OAuth2:

Grant Type: Client Credentials
Access Token URL: https://api.avizuai.com.br/oauth2/token
Client ID: o client_id fornecido
Client Secret: o client_secret fornecido
Scope: escopos solicitados, separados por espaço
Authentication: Send as Headers (recomendado)

O n8n cuida automaticamente da renovação do token quando ele expira.

Erros comuns

Status	Causa típica
`400 invalid_request`	Parâmetros faltando ou mal formados na chamada a `/oauth2/token`
`401 invalid_client`	`client_id` ou `client_secret` inválidos
`400 invalid_scope`	Escopo solicitado não foi autorizado para este cliente
`401 invalid_token`	Token expirado ou inválido na chamada à API
`403 insufficient_scope`	Token válido, mas sem escopo para o endpoint chamado

Próximos Passos

🔒 Autenticação 💬 Mensagens 🔌 Webhooks