Autenticação
Chaves de API com permissões mínimas, ambientes, números e IPs permitidos, limite próprio, validade, rotação sem parada e revogação.
Toda chamada leva uma chave de API no cabeçalho Authorization:
Authorization: Bearer zz_live_9f2c...Sem chave, com chave inválida, vencida ou revogada, a resposta é 401 com reason: API_AUTH_REQUIRED (ou API_AUTH_REVOKED). A única rota sem chave é GET /, que descreve a API.
curl -X POST "https://api.zynzap.com.br/v1/rpc/GetApiKeyIdentity" \
-H "Authorization: Bearer $ZYNZAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request": {}
}'Criar uma chave
No painel, em API e integrações → Nova chave. É preciso ter a autenticação em duas etapas ativa; se a última confirmação de identidade tiver mais de 10 minutos, o painel pede o código do autenticador. O segredo aparece uma única vez (o Zynzap guarda só o hash).
Ambientes: zz_live_ e zz_test_
| Prefixo | Ambiente | Observação |
|---|---|---|
zz_live_ | Produção | Use só no sistema real. |
zz_test_ | Teste | Para desenvolvimento e homologação. |
wl_live_, wl_test_ | Legado | Chaves criadas antes do nome Zynzap. Continuam funcionando. |
O ambiente é um rótulo: chaves de teste acessam a mesma conta, enviam mensagens reais e consomem saldo. Ele existe para você nunca colar a chave de produção num ambiente de testes por engano. Para testar, envie para os seus próprios números.
Permissões (scopes)
Cada chave tem permissões explícitas e nunca passa das permissões do papel de quem a criou. Cada operação da referência informa a permissão que exige; sem ela, a resposta é 403.
| Permissão | O que libera |
|---|---|
sessions:read | Lista números e consulta o status de conexão. |
sessions:manage | Conecta, desconecta, reconecta e exclui números. |
messages:send | Envia mensagens de texto e mídia (envios pagos consomem saldo). |
messages:revoke | Apaga para todos uma mensagem já enviada. |
messages:view_once | Lê e gerencia mídias de visualização única recebidas. |
events:read | Recebe eventos em tempo real (stream e webhooks). |
dashboard:read | Lê os números do painel (Visão geral). |
groups:read / groups:manage | Lista grupos / altera participantes, nome, descrição e permissões. |
product:inbox | Lê e responde conversas do Atendimento, notas e chamadas. |
product:contacts | Contatos e dados do CRM da empresa inteira. |
product:campaigns | Campanhas, listas, segmentos e recuperação. |
product:templates | Modelos de mensagem e diálogos. |
product:media | Biblioteca de mídias. |
product:flows | Fluxos (bots). |
product:warmup | Aquecimento de números. |
product:ai | Assistente de IA. |
O painel oferece modelos prontos:
| Modelo | Permissões |
|---|---|
| Somente leitura | sessions:read, groups:read, events:read, dashboard:read |
| Envio de mensagens | sessions:read, messages:send, events:read |
| Atendimento | sessions:read, product:inbox, messages:send, messages:revoke, messages:view_once, events:read |
| Campanhas | sessions:read, events:read, product:campaigns, product:contacts, product:templates, product:media |
| Administração completa | Tudo o que o seu papel permite |
Números permitidos
Uma chave pode alcançar todos os números ou só os selecionados. Restrita, ela só enxerga esses números e os grupos, conversas e eventos deles; qualquer outro identificador responde 404. Permissões da conta inteira (dashboard:read e product:*, exceto product:inbox) não combinam com números restritos.
Com Permitir criar e parear números (exige sessions:manage), a chave pode criar números pela API até o máximo definido; cada número criado entra na lista da chave e ocupa uma vaga do plano. Veja Números (sessões).
IPs permitidos
Opcional: até 50 IPv4, IPv6 ou faixas CIDR (ex.: 203.0.113.10, 198.51.100.0/24). Chamadas de outros endereços recebem 403 com reason: API_KEY_IP_FORBIDDEN. Use quando o seu servidor tiver IP fixo.
Limite próprio da chave
Opcional, de 1 a 120 requisições por minuto. Acima dele: 429 com reason: API_KEY_RATE_LIMITED. O limite da conta continua valendo. Veja Limites.
Validade, rotação e revogação
- Validade: 30 dias, 90 dias, 1 ano, data personalizada (até 3 anos) ou sem expiração. Prefira prazos definidos.
- Rotacionar segredo: gera um segredo novo para a mesma chave (permissões, limites e histórico continuam). O antigo para imediatamente, em 1 hora ou em 24 horas; durante a carência os dois funcionam, o que permite trocar sem derrubar a integração.
- Revogar: encerra o acesso na hora, inclusive streams abertos e webhooks. Não pode ser desfeito.
- Desativar o segundo fator da conta revoga as chaves de quem desativou.
Criar, editar e rotacionar ficam na auditoria de segurança da empresa.
Boas práticas
- Uma chave por sistema, com o mínimo de permissões e números.
- Guarde a chave em variável de ambiente ou cofre de segredos; nunca em repositório, front-end ou app móvel.
- Use IPs permitidos quando possível e rotacione periodicamente com carência.
- Se a chave vazar, revogue e crie outra.