Autenticação e chaves de API
Como a chave de API da Astrify Flows funciona, quais escopos existem, validade, IPs permitidos, rotação e registro de uso.
Toda requisição à API aberta é autenticada por uma chave de API enviada no cabeçalho Authorization. O login da plataforma (sessão do navegador) não vale na API.
GET /v1/me HTTP/1.1Host: api2.astrify.com.brAuthorization: Bearer SUA_CHAVE_DE_APIA chave tem o formato astrify_<id>_<segredo>. O trecho astrify_<id> é o prefixo, a única parte que a plataforma volta a mostrar depois da criação.
A chave pertence a uma empresa
- A chave é da empresa do usuário que a criou e nunca acessa dados de outra empresa. Um
empresa_iddiferente na URL ou no corpo devolve403. - A chave age em nome do usuário que a criou. Vale o menor dos dois: a permissão do cargo desse usuário e os escopos da chave. Se o usuário for desativado, a chave para de funcionar.
- Chaves criadas por usuários da equipe da plataforma (suporte) valem, no máximo, como administrador da própria empresa.
Quem pode criar chaves
Em Configurações → API aberta, os administradores criam, rotacionam e revogam chaves. Outros cargos só têm acesso se receberem a permissão API aberta (ver, criar, revogar) em Cargos e acesso. Uma chave de API nunca gerencia outras chaves.
Criar uma chave
-
Em Configurações → API aberta, clique em Nova chave.
-
Preencha:
- Nome: de 2 a 80 caracteres, para você reconhecer a integração (ex.: “Integração com o ERP”).
- Expira em: 30 dias, 90 dias, 180 dias, 1 ano ou 2 anos.
- IPs permitidos (opcional): um por linha ou separados por vírgula, até 20. Vazio aceita qualquer IP.
- Permissões: os escopos que a integração precisa (há o atalho Selecionar todas).
-
Clique em Criar chave, copie a chave e só então confirme em Já guardei a chave.
Cada empresa pode ter até 20 chaves ativas ao mesmo tempo. Ao tentar criar a 21ª, a resposta é 409 e é preciso revogar alguma antes.
Escopos
A regra é simples: requisições GET pedem <recurso>:read; os demais métodos (POST, PATCH, PUT, DELETE) pedem <recurso>:write, que já inclui a leitura. Sem o escopo, a resposta é 403 com a mensagem Escopo necessário: <escopo>. A rota GET /v1/me aceita qualquer chave válida.
| Escopo | O que permite |
|---|---|
leads:read / leads:write |
Ler leads, funis e etapas / criar e editar leads |
contatos:read / contatos:write |
Ler contatos / criar e editar contatos |
funis:read |
Ler funis, etapas, origens e motivos de perda |
produtos:read / produtos:write |
Ler o catálogo de produtos / criar e editar produtos |
propostas:read / propostas:write |
Ler propostas / criar e enviar propostas |
etiquetas:read / etiquetas:write |
Ler etiquetas / criar e editar etiquetas |
equipes:read / equipes:write |
Ler equipes e membros / criar e editar equipes e atribuir ou remover usuários |
quadros:read / quadros:write |
Ler quadros, colunas e cards / criar e editar quadros, colunas e cards |
tarefas:read / tarefas:write |
Ler tarefas / criar e editar tarefas |
workflows:read / workflows:write |
Ler Workflows e execuções / disparar Workflows |
mensagens:read / mensagens:write |
Ler instâncias de WhatsApp, mensagens agendadas e rápidas / enviar mensagens de WhatsApp e agendar mensagens |
atendimento:read |
Ler conversas e mensagens do atendimento (respeita a visibilidade do usuário da chave) |
campanhas:read / campanhas:write |
Ler campanhas de WhatsApp / pausar e retomar campanhas |
email:read / email:write |
Ler listas e campanhas de e-mail marketing / criar listas, adicionar contatos às listas e enviar e-mail transacional |
notificacoes:read / notificacoes:write |
Ler as notificações do usuário da chave / marcar como lidas |
relatorios:read |
Ler relatórios |
O escopo exigido por cada rota aparece na Referência da API.
O que não é liberado por API
Algumas ações só podem ser feitas no painel, nunca por chave: excluir quadros e funis, configurar funis, origens e motivos de perda, webhooks e automações de leads, roleta, regras de atraso, cargos e permissões, instâncias de canais, criação de campanhas de disparo em massa, cobrança e credenciais. Chamar uma rota que não faz parte da API aberta devolve 403 com Esta rota não está disponível para chaves de API.
Validade, revogação e rotação
- Status: na lista de chaves, cada uma aparece como Ativa, Expirada ou Revogada.
- Revogar: a chave deixa de funcionar imediatamente (em poucos segundos em todos os servidores). Não dá para desfazer.
- Rotacionar: cria uma chave nova com o mesmo nome, permissões, IPs e prazo. Com Revogar a chave antiga agora marcado, a antiga para na hora; desmarcado, as duas funcionam até você revogar a antiga, para trocar a integração sem ficar fora do ar.
IPs permitidos
Se a chave tiver IPs permitidos, chamadas de qualquer outro IP recebem 403 com IP não autorizado para esta chave. Use quando a integração roda num servidor com IP fixo.
Registro de uso
Cada chamada feita com a chave fica registrada (método, rota, IP e horário). Na lista de chaves você vê o Último uso e o total de chamadas nas últimas 24 h; em Últimas chamadas aparecem as chamadas mais recentes de uma chave.
Boas práticas
- Uma chave por integração, só com os escopos necessários. Se o sistema só lê leads, use
leads:read. - Segredo fora do código: guarde a chave em variável de ambiente ou num cofre de segredos. Nunca em JavaScript de site, aplicativo de celular ou repositório. A API deve ser chamada do seu servidor.
- Se vazar, revogue na hora e crie (ou rotacione) outra.
- Restrinja por IP quando o servidor tiver IP fixo.
- Prefira validade curta para integrações temporárias e rotacione as permanentes de tempos em tempos.