Chave de API da conta

A chave de API da conta permite construir integrações entre a sua conta do Nexus e qualquer outro sistema, sem compartilhar login e sem dar poder além do necessário. Ela é a credencial pensada para o caminho "construir a minha própria integração".

Principais vantagens

• Simples: você gera a chave no painel da própria conta e gerencia tudo por lá, sem abrir chamado.
• Segura: você escolhe os escopos. A chave só faz o que foi liberado, e nada mais.
• Para toda a conta: uma chave alcança todas as conexões da conta, dentro dos escopos.
• Com prazo: validade opcional de 30 dias, 90 dias, 1 ano ou sem vencimento.
• Revogável na hora: revogou, parou. Não há janela de carência.

Qual é a diferença para a chave da linha?

A chave da linha (nx_live_) pertence a um único chip e só opera aquele chip. A chave da conta (nx_acct_) pertence à conta inteira, carrega escopos, tem validade opcional e revogação imediata. Para integrar um sistema, use a chave da conta.

Qual é a diferença para a sessão do painel?

A sessão é de uma pessoa e tem o papel dela. A chave é de um sistema e tem escopos. A chave da conta não cria chips, não configura webhooks e não gerencia chaves: essas ações exigem sessão de dono ou administrador. Isso é de propósito: credencial de integração nunca fabrica outra credencial.

Como uso a chave?

Envie a chave no cabeçalho x-api-key em toda requisição. O cabeçalho Authorization: Bearer com a mesma chave também é aceito.

curl https://nexus.socialfy.me/api/wa/instances \
  -H "x-api-key: nx_acct_SUA_CHAVE"

Cada operação da referência da API diz qual escopo exige na entrada AccountApiKey da lista de segurança dela. Hoje a chave da conta é aceita em:

Qualquer outra rota recusa a chave com 403 e code: ACCOUNT_API_ROUTE_NOT_ALLOWED, mesmo que a chave seja válida. A lista cresce por versão, e cada acréscimo entra no changelog.

Testando a chave com chamadas reais

1. Liste as conexões. A resposta traz o instanceId de cada linha.

curl https://nexus.socialfy.me/api/wa/instances \
  -H "x-api-key: nx_acct_SUA_CHAVE"

2. Consulte o estado de uma linha.

curl https://nexus.socialfy.me/api/wa/status/comercial-sp \
  -H "x-api-key: nx_acct_SUA_CHAVE"

3. Envie uma mensagem de texto para um contato de teste, com uma chave de idempotência própria.

curl -X POST https://nexus.socialfy.me/api/send \
  -H "x-api-key: nx_acct_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: teste-2026-10-09-0001" \
  -d '{"instanceId":"comercial-sp","to":"+5511999990000","type":"text","message":"Teste de integração"}'

Um 200 confirma que o pedido entrou na fila. Confirme a entrega pelo histórico do atendimento ou pelo webhook message_sent.

Se a chave não tiver messages:send, o passo 3 responde 403 com code: ACCOUNT_API_SCOPE_REQUIRED. Isso é o escopo funcionando.

Como gerencio as chaves?

Quem pode criar

Somente o dono ou um administrador da conta. Membro vê a tela com o aviso de que precisa pedir a quem administra. Um operador da plataforma que entra na sua conta para dar suporte também não cria chave (pode listar e revogar): credencial durável da conta nasce só de quem é da conta.

Onde encontro

No painel, abra o menu da conta e entre em Desenvolvedores. O mesmo lugar aparece como o card Chave de API em Conta > Integrações. A tela lista todas as chaves com nome, prefixo e final, escopos, último uso, vencimento e situação.

A chave inteira nunca é exibida de novo. A lista mostra só o começo e o final, o suficiente para você reconhecer qual é qual.

Como criar uma chave nova

1. Clique em Criar chave.
2. Dê um nome que identifique a integração, como automação do n8n.
3. Marque os escopos que ela precisa. O menor conjunto que resolve.
4. Escolha a validade: 30 dias, 90 dias, 1 ano ou sem vencimento.
5. Clique em Gerar chave.
6. Copie a chave agora e guarde num cofre de senhas. Esta é a única vez que ela aparece inteira.
7. Clique em Já guardei.

Uma conta pode ter até 20 chaves ativas ao mesmo tempo. Ao chegar no teto, revogue uma antes de criar outra.

Como edito as permissões de uma chave?

Não se edita. Escopo é parte da identidade da chave: quem tem a chave sabe exatamente o que ela pode. Para mudar permissões, crie uma chave nova com os escopos certos, troque na integração e revogue a antiga.

Como giro a chave?

Mesma receita: crie a nova, troque na integração, revogue a antiga. Enquanto as duas existirem, as duas funcionam, então a troca não derruba a integração.

Como revogo uma chave?

Na lista, clique em Revogar na linha da chave e confirme. A revogação vale na hora: toda requisição com aquela chave passa a responder 401. A chave fica na lista como Revogada, com a data, para auditoria. Revogar duas vezes não dá erro.

Boas práticas de segurança

• Guarde a chave em cofre de senhas ou variável de ambiente. Nunca em frontend, app móvel, planilha, log ou commit.
• Uma chave por integração, com o nome dela. Quando algo vazar, você sabe o que revogar.
• Dê o menor escopo possível. Leitura e envio são escopos separados de propósito.
• Use validade em integrações temporárias e em testes.
• Revise a lista de chaves periodicamente. Chave sem uso há meses é candidata a revogação.
• Monitore o último uso. Uso em horário ou volume estranho é sinal de vazamento.

E se a minha chave foi comprometida?

1. Revogue na hora, antes de investigar. A revogação é imediata.
2. Crie uma chave nova e troque na integração legítima.
3. Olhe o histórico de envios da conta no período e avise o suporte se encontrar envio que não reconhece.
4. Descubra por onde vazou (log, commit, print, planilha) e feche a porta.

Como apago uma chave que não uso mais?

Revogue. A chave revogada deixa de funcionar e permanece na lista só como registro. Não há exclusão física na versão atual, e isso é proposital: a trilha de quando cada credencial morreu faz parte da segurança da conta.

Formato e limites