API Keys

Nível de acesso requerido

Admin ou Super Admin

Para que servem as API Keys?

API Keys permitem que sistemas externos acessem a API do Flowi Agentic de forma programática, sem login de usuário. São usadas para:

• Integrações com ERPs, sistemas fiscais, portais
• Automações externas que precisam iniciar processos ou consultar dados
• Scripts e ferramentas de linha de comando

Criando uma API Key

1. Acesse Integração → API Keys
2. Clique em Nova API Key
3. Informe um nome descritivo (ex.: "Integração ERP SAP")
4. Defina o limite de requisições por minuto — padrão 100, 0 para ilimitado
5. Marque os escopos que a integração precisa — pelo menos um é obrigatório
6. Clique em Gerar

A chave gerada é exibida apenas uma vez. Copie e guarde em local seguro antes de fechar a janela.

O limite e os escopos também podem ser alterados depois, na mesma tela, em Editar chave. A mudança vale a partir da requisição seguinte, sem reiniciar nada.

O limite conta requisições por minuto daquela chave. Ao ultrapassá-lo, a API responde 429 Too Many Requests até o minuto virar. Um 0 desliga a contagem: use com cuidado, porque é a única proteção contra uma integração em laço.

O número aqui é o da instalação inteira, com um pod ou com cinco: a contagem fica numa tabela compartilhada, não na memória de cada réplica. Até 2026-08-28 não era assim — duas réplicas entregavam o dobro do orçamento enquanto esta tela seguia mostrando o número original. A janela é fixa, não deslizante: na virada do minuto uma integração pode gastar a cota inteira duas vezes seguidas.

Os escopos: o que cada um abre

Existem dois escopos, e são os únicos que a tela oferece:

Escopo	O que abre	Métodos HTTP
read	Toda leitura da API do tenant: listar instâncias, consultar uma tarefa, ler uma coleção de CMS, baixar um relatório	GET, HEAD, OPTIONS
write	Toda escrita: iniciar processo, completar tarefa, gravar no CMS, revogar algo, apagar um registro	POST, PUT, PATCH, DELETE

Os dois não se implicam. Uma chave marcada só com write é recusada num GET, exatamente como uma chave só de read é recusada num POST. Uma integração que lê e escreve carrega os dois.

Uma requisição sem o escopo necessário recebe 403 Forbidden com a explicação de qual escopo faltou:

{
  "error": "Forbidden",
  "message": "Esta chave de API tem os escopos [read] e o método POST exige o escopo 'write'. Marque esse escopo na chave em Integração → API Keys, ou use uma chave que já o tenha."
}

O corte é pelo método HTTP, não pela rota. A consequência prática é uma só: um endpoint que só consulta mas é exposto como POST — uma busca com filtro no corpo, por exemplo — exige write. Se a integração só lê e mesmo assim precisa de write por causa disso, é esperado.

As chaves que já existiam receberam os dois escopos

Até 2026-09-03 o campo de escopo era texto livre e nenhuma rota o consultava: uma chave criada como read tinha exatamente o alcance de uma criada como write, e um escopo digitado errado — forms:submit, que nunca existiu — não restringia nada.

Ao subir a versão que passou a exigir escopo, toda chave já cadastrada recebeu read e write, inclusive as que estavam em branco e as que tinham escopo inventado. Nenhuma integração parou de funcionar por causa da mudança, e nenhuma ficou mais restrita do que estava.

Isso significa que a chave somente-leitura que você acredita ter hoje provavelmente não é uma. Abra Integração → API Keys, clique em Editar chave em cada linha e desmarque o write das integrações que só leem. É a única forma de a restrição passar a valer.

O detalhe técnico, com o formato das autoridades e o corpo da resposta 429, está em API REST → Autenticação.

Segurança

• Nunca compartilhe a API Key em repositórios de código ou ambientes não seguros
• Cada integração deve usar sua própria chave separada
• Rotacione as chaves periodicamente

Usando a API Key

Inclua a chave no header de cada requisição:

X-API-Key: sua-chave-aqui

A chave identifica o tenant automaticamente — não envie o X-Tenant-ID: numa rota /api/a/* o cabeçalho é recusado com 400 antes de a chave ser resolvida. O tenant vem da própria chave.

Revogando uma API Key

Clique em Revogar na linha da chave. A revogação é imediata — qualquer sistema usando aquela chave perderá o acesso instantaneamente.

Boas práticas

Tenha uma política de rotação periódica das chaves. Ao rotacionar, crie a nova chave, atualize o sistema externo e só então revogue a chave antiga.