Autorização

Toda requisição à API precisa dizer quem é e o que pode fazer. O Nexus aceita quatro formas de fazer isso, e cada uma existe para um uso diferente. Escolher a certa é o que evita credencial com poder demais rodando em lugar errado.

As três credenciais

Credencial	Prefixo ou formato	Para quem é	Alcance	Onde nasce
Chave de API da conta	`nx_acct_`	Integração de sistema (n8n, Make, código próprio)	Toda a conta, limitada pelos escopos escolhidos	Conta > Desenvolvedores
Chave da linha	`nx_live_`	Automação presa a um único número	Só o chip da chave	Configuração do chip
Sessão do painel	JWT no `Authorization: Bearer`	Pessoa usando o painel ou script com login humano	Tudo o que o papel da pessoa permite	Login no Nexus

Apps de terceiros instalados por qualquer conta (OAuth 2.0) estão descritos em Apps de terceiros. Módulos em prévia, como afiliação e checkout, têm credenciais próprias que entram aqui quando o módulo virar contrato público.

Qual é a diferença entre a chave da conta e a chave da linha?

A chave da linha nasceu primeiro e vale para um chip só: ela só consulta o estado daquele chip e envia por ele. É boa para um robô que cuida de um número.

A chave da conta vale para todas as conexões da conta e carrega escopos. É a credencial de integração: um sistema externo que precisa listar as linhas, consultar estado e enviar por qualquer uma delas usa a chave da conta. Ela também tem validade opcional e revogação imediata.

Qual é a diferença entre a chave da conta e a sessão do painel?

A sessão é de uma pessoa, expira, e tem o papel dela (dono, administrador ou membro). As ações administrativas, como criar chip, configurar webhook e gerenciar chaves, exigem sessão de propósito: credencial de integração nunca cria outra credencial.

A chave da conta é de um sistema, não expira a menos que você escolha, e só faz o que os escopos permitem. Use a sessão para administrar e a chave para operar.

Como a credencial chega na requisição

# Chave da conta ou da linha, no cabeçalho dedicado
curl https://nexus.socialfy.me/api/wa/status/comercial-sp \
  -H "x-api-key: nx_acct_SUA_CHAVE"

# A mesma chave também é aceita como Bearer
curl https://nexus.socialfy.me/api/wa/status/comercial-sp \
  -H "Authorization: Bearer nx_acct_SUA_CHAVE"

O servidor reconhece a credencial pelo prefixo. O JWT da sessão continua no mesmo cabeçalho Authorization.

O que acontece quando a credencial não serve

Situação	Resposta
Credencial ausente, desconhecida, revogada ou vencida	`401`
Credencial válida, mas a operação não aceita esse tipo de credencial	`403`
Credencial válida, mas sem o escopo que a operação exige	`403` com `code: ACCOUNT_API_SCOPE_REQUIRED`
Muitas tentativas inválidas seguidas da mesma origem	`429` por um curto período

Os códigos completos estão em Erros.

Boas práticas que valem para todas

Uma credencial por integração. Se o n8n e o Make falam com o Nexus, cada um tem a sua chave, com o nome deles.
O menor escopo que resolve. Uma integração que só lê não precisa de messages:send.
Cofre de senhas ou variável de ambiente. Nunca frontend, log, planilha ou commit.
Validade quando a integração é temporária. Chave sem vencimento é para o que vai durar.
Suspeita de vazamento é revogação na hora, antes de investigar.