Chaves de API
As chaves de API permitem que sistemas externos enviem dados para o Waizer ou acessem recursos da plataforma de forma programática. São o pilar central da Integração via API.
Para a especificação completa de todos os endpoints, parâmetros e respostas, consulte a referência completa da API.
Governança de credenciais
O ciclo de vida das chaves é gerenciado na página da organização (rodapé do menu lateral → Gerenciar), na seção Chaves de API.
Criação, edição e exclusão de chaves são atribuições exclusivas de Administradores.
Criando uma chave de API
- Clique em Criar nova chave.
- Atribua um nome que identifique claramente a aplicação ou ambiente (ex:
bot-atendimento-producao,pipeline-ci-staging). - Selecione ao menos um escopo de acesso (veja a seção abaixo). O botão de criação fica desabilitado sem escopos selecionados.
- Clique em Criar chave.
- Copie o token gerado imediatamente. A chave completa é exibida apenas uma vez. Após fechar o modal, não é possível recuperá-la.
Na listagem, apenas os primeiros caracteres do token são exibidos (ex: waizer_12345...) para identificação visual - o valor completo nunca é mostrado novamente.
Armazene a chave em um gerenciador de segredos ou variável de ambiente criptografada no servidor. Se o token for perdido, crie uma nova credencial e atualize todas as integrações que a utilizam.
Escopos de acesso
Cada chave de API opera com o conjunto de escopos selecionados na criação. Conceda apenas os escopos necessários para cada sistema.
Membros
| Escopo | O que permite |
|---|---|
users:read | Listar e buscar membros da organização. |
users:write | Adicionar, atualizar e remover membros da organização. |
Tarefas
| Escopo | O que permite |
|---|---|
jobs:read | Consultar status de jobs de importação. |
jobs:write | Disparar novos jobs de importação. Limite: 1 job por hora por integração. |
Mensagens
| Escopo | O que permite |
|---|---|
messages:write | Ingerir mensagens via API. Limite: até 10.000 mensagens por requisição. |
Editando uma chave
Abra o menu ⋮ ao lado da chave e selecione Editar chave. O modal permite alterar o nome e os escopos sem invalidar o token - as integrações existentes continuam funcionando.
Apagando uma chave
Abra o menu ⋮ ao lado da credencial e selecione Apagar chave.
A exclusão é instantânea e irreversível. Qualquer aplicação que use o token perde o acesso no mesmo momento. Atualize as variáveis dos seus servidores antes de concluir.
Diretrizes de segurança
- Um token por sistema: aloque uma chave distinta para cada serviço ou ambiente (
production,staging,development). Se uma credencial for comprometida, a exclusão é isolada e não afeta outros fluxos. - Somente server-side: nunca exponha chaves de API em código executado no navegador.
- Sem hardcode: não armazene credenciais em repositórios de código. Use arquivos
.enve adicione-os ao.gitignore. - Monitoramento: diante de qualquer comportamento inesperado, apague o token imediatamente.
Auditoria periódica
A listagem exibe a data do último uso de cada chave - ou Nunca se ela ainda não foi utilizada. Use essa informação para identificar tokens órfãos.
Revise a lista a cada 3 meses. Remova credenciais com nomes ambíguos ou cujo uso não possa ser mapeado. Tokens sem uso ativo são superfície de ataque desnecessária.