Ligar um agente de IA ao 4Keyless

Um agente de IA (ou qualquer automação) usa o 4Keyless por um proxy HTTP. O agente se autentica no proxy com a chave do agente; o proxy confere a liberação, injeta a credencial real do sistema (senha, API key, token OAuth, certificado, código 2FA), encaminha a requisição e grava o registro de acesso. O agente nunca vê o segredo.

Se o seu agente fala MCP (Claude, Cursor e afins) e as ferramentas expostas bastam para a tarefa, prefira o MCP Gateway: não há certificado para confiar nem proxy para configurar.

Endereços

1. Criar o agente e a chave

1. No painel, abra Agentes e clique em Novo agente.
2. Escolha o tipo Bot, dê um nome e escolha o grupo do agente, no campo Grupo. É pelo grupo que as liberações chegam a ele.
3. Salve. A janela Chaves do agente mostra a chave, no formato 4k_bot_.... Ela aparece uma única vez: copie agora.

4. Garanta que o grupo do agente tenha uma liberação para os acessos que ele vai usar. Veja Liberar um acesso e Políticas.

A chave de bot não expira. Rotacionar chave, na linha do agente, emite outra e invalida a anterior na hora. Desativar o agente corta a chave imediatamente.

2. Instalar a skill (agentes de IA)

A skill ensina o agente a usar o 4Keyless: variáveis de proxy, certificado, descoberta, escolha do titular, sinais de bloqueio e o que fazer em cada um. Ela está em https://4keyless.io/SKILL.md, com o script de navegador em https://4keyless.io/skill-scripts/browse.js.

No Claude Code, por exemplo:

mkdir -p ~/.claude/skills/4keyless/scripts
curl -fsSL https://4keyless.io/SKILL.md -o ~/.claude/skills/4keyless/SKILL.md
curl -fsSL https://4keyless.io/skill-scripts/browse.js -o ~/.claude/skills/4keyless/scripts/browse.js

Skills com o procedimento de um acesso específico (ids reais, titulares, domínios) são exportadas no painel, em MCP Gateway, aba Skills, botão Baixar como SKILL.md.

3. Confiar no certificado do 4Keyless

O proxy abre o HTTPS para injetar a credencial, então o cliente HTTP do agente precisa confiar no certificado do 4Keyless. Baixe o arquivo fora do proxy (antes de exportar as variáveis de proxy, ou com api.4keyless.io em NO_PROXY):

curl -fsSL https://api.4keyless.io/api/v1/certificate/download -o ~/4keyless-ca.crt

Prefira confiar por processo, sem permissão de administrador:

Para configurar uma máquina Linux inteira de uma vez, com FKL_AGENT_KEY já exportada:

curl -fsSL https://4keyless.io/install.sh | bash

O script baixa o certificado e o instala no sistema (pede sudo), grava ~/.config/4keyless/env.sh com as variáveis de proxy e de certificado, carrega esse arquivo no .bashrc, .zshrc e .profile, configura curl, wget e git e testa a conexão. Opções: --cert-only (só o certificado), --system-wide (também /etc/environment e apt) e --uninstall. No macOS, curl -fsSL https://4keyless.io/install-macos-ca.sh | bash instala o certificado no chaveiro. Em computadores de pessoas, o 4Keyless Desktop e o artigo Instalar o certificado de segurança cobrem o mesmo passo.

4. Mandar as chamadas pelo proxy

O proxy aceita a chave de dois jeitos:

Proxy-Authorization: 4Keyless <chave do agente>
Proxy-Authorization: Basic base64("agent:<chave do agente>")

No formato Basic o usuário é ignorado e a senha é a chave, o que permite usar a URL de proxy padrão de qualquer cliente HTTP:

export HTTPS_PROXY="http://agent:${FKL_AGENT_KEY}@proxy.4keyless.io:8080"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="agent.4keyless.io,api.4keyless.io,mcp.4keyless.io"

NO_PROXY tira do caminho os endereços do próprio 4Keyless, que não precisam de injeção.

Depois, chame o sistema de destino direto, pelo endereço dele. Há dois estilos, conforme a configuração do acesso:

• Sem credencial: não mande cabeçalho de autenticação. O proxy coloca o certo no caminho (num sistema OAuth, um Authorization: Bearer sempre renovado). O que você mandar em Authorization é sobrescrito.
• Sentinela: onde iria o segredo, mande o texto-sentinela definido no acesso. O proxy o troca pelo valor real.

Na dúvida, comece sem credencial: um 401 do sistema de destino na primeira tentativa indica que o acesso espera a sentinela.

curl

curl --cacert ~/4keyless-ca.crt \
     --proxy "http://agent:${FKL_AGENT_KEY}@proxy.4keyless.io:8080" \
     https://api.exemplo.com.br/v1/clientes

Python

import os
import requests

proxy = f"http://agent:{os.environ['FKL_AGENT_KEY']}@proxy.4keyless.io:8080"
resp = requests.get(
    "https://api.exemplo.com.br/v1/clientes",
    proxies={"http": proxy, "https": proxy},
    verify=os.path.expanduser("~/4keyless-ca.crt"),
    timeout=120,
)
print(resp.status_code, resp.headers.get("X-4Keyless-Blocked"))

Node.js

Com o undici (npm i undici), rodando com NODE_EXTRA_CA_CERTS=~/4keyless-ca.crt:

import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent({
  uri: 'http://proxy.4keyless.io:8080',
  token: `4Keyless ${process.env.FKL_AGENT_KEY}`,
});

const resp = await fetch('https://api.exemplo.com.br/v1/clientes', { dispatcher });
console.log(resp.status, resp.headers.get('x-4keyless-blocked'));

5. Descobrir o que o agente alcança

A Agent API responde, em JSON, só o que a liberação do agente permite. Use Bearer:

curl -H "Authorization: Bearer $FKL_AGENT_KEY" https://agent.4keyless.io/api/systems

Qualquer URL cujo host case com os domains de um acesso recebe a credencial quando passa pelo proxy. O type indica a ferramenta: rest_api e graphql são chamadas HTTP comuns; web_app pede um navegador de verdade (veja abaixo).

Escolher o titular e o local da conexão

Sem escolha, o proxy usa o titular padrão da liberação. Para agir em nome de outro titular, peça uma capacidade de acesso uma vez e mande o valor em toda requisição ao domínio:

curl -X POST https://agent.4keyless.io/api/access-codes \
  -H "Authorization: Bearer $FKL_AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"systems":[{"system_id":"<id do acesso>","group_id":"<id do titular>"}]}'

A resposta traz codes, com um value por domínio. Envie-o no cabeçalho X-4Keyless-Access. O titular fica fixo na capacidade e é lido no servidor: nada que você mande depois o troca. Para escolher o local da conexão por requisição, mande X-4Keyless-Exit-Proxy: <id> com um id de /api/exit-proxies. Os dois cabeçalhos são removidos antes de a requisição seguir.

Sistemas web (web_app)

Sistemas do tipo web_app precisam de navegador: o 4Keyless executa a automação de login dentro da página, e baixar o HTML com curl devolve só o formulário. Use Playwright com o proxy no contexto do navegador (proxy: { server, username: 'agent', password: process.env.FKL_AGENT_KEY }) e um user agent de Chrome comum: portais públicos costumam recusar o HeadlessChrome com 403 antes de a requisição chegar ao 4Keyless. O browse.js da skill já faz isso:

npm i playwright && npx playwright install chromium
node ~/.claude/skills/4keyless/scripts/browse.js https://sistema.exemplo.com.br/login --shot tela.png

Se algo der errado

A lista completa, com os limites por plano, está em Erros e limites.