Autenticação e autorização
Os dois cabeçalhos exigidos em toda requisição, como gerar a chave de API e o que ela permite fazer.
Os dois cabeçalhos exigidos em toda requisição, como gerar a chave de API e o que ela permite fazer.
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.
curl https://api-publica.sunchat.com.br/v1/etiquetas \
-H "X-Ambiente: 12345" \
-H "X-Authorization: X-Chave-Api sua-chave-aqui"
| Cabeçalho | Valor | Obrigatório |
|---|---|---|
X-Ambiente | O número da sua conta, só os dígitos: 12345 | Sim (ou X-Canal) |
X-Authorization | X-Chave-Api seguido da chave | Sim |
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.
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.
Abra a tela Chave de API
No menu lateral, vá em Configurações > Integrações > Chave de API.
Gere a chave, se ainda não existir
Sem chave, a tela mostra Nenhuma chave gerada. Clique em Gerar chave de acesso.
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.
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:
Liste onde a chave está em uso
Servidores, funções serverless, automações, ferramentas internas.
Gere a nova chave
Em Configurações > Integrações > Chave de API, clique em Gerar nova chave e confirme.
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.
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:
curl https://api-publica.sunchat.com.br/v1/etiquetas \
-H "X-Canal: 3f2a9c10-5b7e-4d81-a6f3-9e0c1b2d4a58" \
-H "X-Authorization: X-Chave-Api sua-chave-aqui"
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.
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.
Falha de autenticação devolve 401 Unauthorized com corpo vazio e o cabeçalho
WWW-Authenticate: X-Chave-Api realm="SunchatPlus". 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:
| Verifique | Sintoma |
|---|---|
O prefixo X-Chave-Api no valor de X-Authorization | A causa mais comum |
O nome do cabeçalho: X-Authorization, não Authorization | Authorization é ignorado |
| Se a chave não foi regerada depois que você a copiou | Chave antiga não funciona mais |
Se X-Ambiente é o número da conta certa | Conta errada também dá 401 |
| Se a conta está ativa | Conta inativa não autentica |
Os demais códigos de erro estão em Erros.
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.