A API pública se autentica por chave de API, enviada em cabeçalhos HTTP. Não existe login, nem fluxo de token, nem prazo de expiração. A chave vale enquanto não for trocada. Toda requisição precisa de dois cabeçalhos. Um identifica a conta, o outro prova que você tem permissão sobre ela.
O prefixo X-Chave-Api faz parte do valor do cabeçalho, com um espaço antes da chave. Enviar só a chave, sem o prefixo, resulta em 401.

​
Onde encontrar o número da conta

O número aparece na tela de escolha de conta, ao entrar na plataforma, no formato Conta #12345. Se você acessa mais de uma conta, cada uma tem seu próprio número e sua própria chave. As duas coisas andam sempre juntas.

​
Como gerar a chave de API

1

Abra a tela Chave de API

No menu lateral, vá em Configurações > Integrações > Chave de API.
2

Gere a chave, se ainda não existir

Sem chave, a tela mostra Nenhuma chave gerada. Clique em Gerar chave de acesso.
3

Copie a chave

O campo Chave de Acesso à API vem mascarado. Use o ícone de olho para revelar e o botão Copiar.
A chave dá acesso total à conta. Quem a tiver pode ler contatos, enviar mensagens em nome da sua empresa e alterar negócios. Guarde-a como você guardaria uma senha de banco de dados: em variável de ambiente ou cofre de segredos. Nunca no código-fonte, em repositório público, em planilha ou em JavaScript que roda no navegador.

​
Rotação da chave

Cada conta tem uma chave por vez. Ao clicar em Gerar nova chave, a chave anterior morre na hora, e toda integração que a usava passa a receber 401 até ser atualizada. A troca precisa de um pouco de planejamento:
1

Liste onde a chave está em uso

Servidores, funções serverless, automações, ferramentas internas.
2

Gere a nova chave

Em Configurações > Integrações > Chave de API, clique em Gerar nova chave e confirme.
3

Atualize todos os pontos de uma vez

Não existe período de convivência entre a chave antiga e a nova.
Se a chave atual vazou em um commit, em um log, num print de tela ou no navegador, gere uma nova imediatamente.

​
Identificando a conta pelo canal

Quando o sistema que integra conhece o ID do canal mas não o número da conta, use X-Canal no lugar de X-Ambiente:
A conta é resolvida a partir do canal informado. X-Ambiente tem precedência: se os dois vierem, o número da conta é usado e o canal é ignorado.

​
O que a chave autoriza

A chave autentica a conta, não um usuário. Isso muda duas coisas na prática. A primeira é que não há papéis nem permissões por chave. Ela alcança todos os endpoints e todos os dados da conta. Se a sua integração precisa de escopo reduzido, o controle tem de ficar do seu lado. A segunda é que as ações não têm autor. O que a API cria não fica atribuído a um usuário da plataforma. Quando o endpoint precisa de um responsável, como ao atribuir um atendimento, o usuário vai no corpo da requisição. Os dados ficam sempre isolados por conta. Uma chave nunca alcança dados de outra conta, mesmo que você informe um ID válido de lá. A resposta é 404.

​
Quando a autenticação falha

Falha de autenticação devolve 401 Unauthorized com corpo vazio e o cabeçalho WWW-Authenticate: X-Chave-Api realm="Novus". Diferente dos outros erros da API, o 401 não traz JSON explicando o motivo. Isso é deliberado, para não revelar se uma conta existe. Se você recebeu 401, verifique nesta ordem: Os demais códigos de erro estão em Erros.

​
Autenticação do servidor MCP

O endereço /mcp, usado por agentes de IA, aceita a mesma chave de API nos mesmos cabeçalhos. Ele também aceita OAuth 2.1 com PKCE, que é o caminho de clientes como o Claude para conectar sem ninguém colar uma chave em arquivo de configuração. Os detalhes estão em Servidor MCP.