Developers
Criar chave de APIEntrar na plataforma

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.1
Host: api2.astrify.com.br
Authorization: Bearer SUA_CHAVE_DE_API

A 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_id diferente na URL ou no corpo devolve 403.
  • 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

  1. Em Configurações → API aberta, clique em Nova chave.

  2. 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).
  3. 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.

Digite para pesquisar em toda a documentação.