API de integração: automatizar a conta pelo seu backend
Crie um usuário de integração, emita a key e use a referência completa da API, que fica no painel em /api-docs.
Open in the panelA API de integração deixa o seu backend fazer, por código, o que o painel faz: cadastrar agentes, titulares e credenciais, montar acessos e liberações, disparar e acompanhar execuções, ler o registro de acessos e consultar plano e consumo. Ela autentica com a key de um usuário de integração, que é um usuário da conta com papel e escopos próprios.
Não confunda com a chave do agente: a chave 4k_bot_ é de quem usa os acessos (pelo proxy ou pelo MCP, veja Ligar um agente de IA); a key 4k_int_ é de quem administra a conta por API.
| Base | https://api.4keyless.io/api/v1 |
| Autenticação | Authorization: Bearer <key de integração> |
| Resposta | { "data": ..., "error": null } ou { "data": null, "error": { "code", "message" } } |
| Formato | JSON, campos em snake_case |
1. Criar o usuário de integração e a key
Só administradores da conta fazem isto.
- No painel, abra Usuários e clique em Nova integração.
- Dê um nome, escolha o papel e os escopos. Os escopos seguem o papel: a integração nunca faz mais do que o papel permite.
- Se quiser a key já, marque Emitir a primeira key agora. Ela aparece uma vez: copie e guarde no seu cofre de segredos.
Para emitir, regenerar ou revogar keys depois, use a ação Keys de API na linha do usuário de integração. Uma integração tem uma key ativa por vez: emitir outra substitui a atual.
| Propriedade da key | Valor |
|---|---|
| Formato | 4k_int_<tenant_id>_<key_id>_<segredo>_<crc> |
| Validade | de 1 a 365 dias, ou indeterminada; o padrão recomendado é 90 dias |
| Faixas de IP | até 32 faixas CIDR (allowed_cidrs); fora delas, 403 ip_not_allowed |
| Rotação por API | POST /integration/key/rotate; a key anterior segue valendo por até 24 horas |
| Onde guardar | só no backend. Nunca em navegador, app distribuído, repositório ou URL |
2. Fazer a primeira chamada
GET /integration/me devolve quem a key é: usuário, papel, escopos e quando ela vence (key_expires_at). Use-o para conferir a configuração e para agendar a rotação.
curl https://api.4keyless.io/api/v1/integration/me \
-H "Authorization: Bearer $FKL_INTEGRATION_KEY"GET /billing/status (escopo billing:read) devolve o plano, os limites e o consumo das cotas do mês.
3. Consultar a referência completa
A referência de cada rota, com corpo, resposta, escopo exigido, erros e um console para testar, fica no painel, em admin.4keyless.io/api-docs. Ela é gerada do código, então acompanha a API. Para abrir pelo painel: Usuários > Keys de API > Ver a referência da API.
A página tem até três documentos, escolhidos no topo:
| Documento | O que cobre | Quem vê |
|---|---|---|
| Integração | as rotas que a key 4k_int_ pode chamar, com o escopo de cada uma | qualquer usuário logado |
| Agentes | proxy, Agent API, MCP Gateway e login do agente humano | qualquer usuário logado |
| Parceiros | as rotas da key de parceiro | só contas com parceria. Veja API de parceiros |
As chamadas feitas pelo console da referência são reais: rodam contra a sua conta, com a trilha de auditoria e o limite da key que você colar. A key não fica salva no navegador.
Agir em nome de um agente
Uma execução sempre roda em nome de um agente, com as liberações e os titulares dele. Com o escopo runs:write, POST /runs recebe o agent_id. Para um agente humano, a integração precisa também do escopo agents:delegate e do papel admin.
Para chamar o proxy direto em nome de um agente, peça um token curto com POST /agents/{id}/delegated-token (escopo agents:delegate, de 60 a 900 segundos, padrão 300, sem renovação) e use-o como Proxy-Authorization: 4Keyless <token>. O registro de acesso mostra a sua integração como quem pediu.
Limites
Por minuto: 120 chamadas por key e 300 por IP; no máximo 60 escritas por key. Acima disso, a resposta é 429 rate_limited. Os demais erros estão em Erros e limites.
Se algo der errado
| Resposta | O que significa |
|---|---|
401 unauthorized | Key inexistente, adulterada ou com formato errado. Sem detalhe, de propósito. |
403 delegation_blocked | Key válida mas bloqueada; o campo reason diz o motivo (key_expired, key_revoked, user_inactive, ip_not_allowed, entre outros). |
403 insufficient_scope | A key não tem o escopo da rota. |
403 route_not_allowed | A rota não está disponível para keys de integração. |
404 not_found em toda rota | A API de integração está desligada neste ambiente. |
429 rate_limited | Limite por minuto atingido. |
Related articles
- Usuários do painel e papéisConvide colegas para administrar o 4Keyless com você e escolha o que cada um pode fazer no painel.
- API de parceiros: oferecer o 4Keyless com a sua marcaComo um parceiro cria e opera contas de clientes pelo próprio backend, com a key de parceiro e a key de integração de cada cliente.
- Erros e limites para quem integraO que cada resposta de erro do proxy, da Agent API, do MCP Gateway e da API de integração significa, e os limites de cada plano.
- Ligar um agente de IA ao 4KeylessCrie a chave do agente, confie no certificado do 4Keyless e mande as chamadas pelo proxy; a credencial é injetada no caminho, sem passar pelo agente.