4Keyless Documentation

4Keyless secures AI agent access to protected systems through a managed gateway. Agents send outbound traffic through the 4Keyless Proxy (or the MCP Gateway); 4Keyless authenticates the agent, applies your access policies, injects credentials from Vault, and routes egress through your exit proxies — without exposing secrets to the agent.

This documentation is organized like an API reference. Start with Authentication, run the Quickstart, then use the API Reference for per-resource details.

Core concepts

Base URLs

HTTPS targets are tunneled with CONNECT on the same proxy port. Standard REST response envelope: { data, meta?, error? }.

🤖 Building an AI agent? Give it SKILL.md — a drop-in skill file that teaches any agent how to authenticate to the proxy, discover its allowed systems and credential groups via the Agent Discovery API, trust the CA certificate, and interpret policy responses.

Authentication

Every request through the proxy or MCP gateway must carry an agent key. Proxied HTTPS traffic is intercepted (MITM), so clients must also trust the 4Keyless CA certificate. Two authentication formats are accepted:

# Format 1 — 4Keyless header (curl, explicit clients)
Proxy-Authorization: 4Keyless <your-agent-key>

# Format 2 — Basic auth (browsers, many HTTP libraries)
Proxy-Authorization: Basic base64(agent:<your-agent-key>)
# commonly embedded in the proxy URL:
# http://agent:<your-agent-key>@proxy.4keyless.io:8080

• The username part of the URL (agent) is ignored — 4Keyless reads the password as the agent key.
• Missing or invalid keys return 407 Proxy Authentication Required.
• Rotate keys any time from Agents > Rotate Key, then update your runtime immediately.

The REST API (/api/v1) uses a workspace JWT instead — see Agents and Errors.

Client setup

Point your agent's outbound HTTP(S) at the proxy and present the agent key. A minimal verified call:

curl --proxy http://proxy.4keyless.io:8080 \
  --proxy-header "Proxy-Authorization: 4Keyless <your-agent-key>" \
  --cacert 4keyless-ca.crt \
  https://example.com/

# Full install — CA + proxy + auth
curl -fsSL https://4keyless.io/install.sh | bash -s -- --key 4k_your_agent_key

# CA only (no agent key)
curl -fsSL https://4keyless.io/install.sh | bash -s -- --cert-only

# System-wide (/etc/environment + apt, requires sudo)
curl -fsSL https://4keyless.io/install.sh | bash -s -- --key 4k_your_agent_key --system-wide

# Uninstall
curl -fsSL https://4keyless.io/install.sh | bash -s -- --uninstall

# Appended by install.sh (idempotent block in ~/.hermes/.env)
AGENT_BROWSER_PROXY=http://proxy.4keyless.io:8080
AGENT_BROWSER_PROXY_USERNAME=user
AGENT_BROWSER_PROXY_PASSWORD=4k_your_agent_key
NODE_EXTRA_CA_CERTS=$HOME/4keyless-ca.crt

./scripts/install-linux-proxy.sh --key 4k_your_agent_key            # full install
FKL_AGENT_KEY=4k_your_agent_key ./scripts/install-linux-proxy.sh    # key via env
./scripts/install-linux-proxy.sh --cert-only                        # CA + trust only
./scripts/install-linux-proxy.sh --key 4k_... --system-wide         # /etc/environment + apt
./scripts/install-linux-proxy.sh --key 4k_... --proxy-host proxy.4keyless.io:8080
./scripts/install-linux-proxy.sh --key 4k_... --no-verify           # skip connectivity test
./scripts/install-linux-proxy.sh --key 4k_... --no-hermes            # skip ~/.hermes/.env
./scripts/install-linux-proxy.sh --uninstall                        # remove shell/proxy config

source ~/.config/4keyless/env.sh

# Test (expect HTTP 200, not 407)
curl --cacert ~/4keyless-ca.crt https://httpbin.org/ip

export FKL_AGENT_KEY="4k_your_agent_key_here"
export FKL_PROXY="http://agent:${FKL_AGENT_KEY}@proxy.4keyless.io:8080"

export HTTP_PROXY="${FKL_PROXY}"
export HTTPS_PROXY="${FKL_PROXY}"
export ALL_PROXY="${FKL_PROXY}"
export http_proxy="${FKL_PROXY}"
export https_proxy="${FKL_PROXY}"
export all_proxy="${FKL_PROXY}"

# Keep local and internal traffic direct
export NO_PROXY="localhost,127.0.0.1,::1"
export no_proxy="${NO_PROXY}"

# Trust the 4Keyless CA (after download)
export SSL_CERT_FILE="$HOME/4keyless-ca.crt"
export REQUESTS_CA_BUNDLE="$HOME/4keyless-ca.crt"
export NODE_EXTRA_CA_CERTS="$HOME/4keyless-ca.crt"

# /etc/environment (Ubuntu/Debian) — no "export" keyword
HTTP_PROXY="http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
HTTPS_PROXY="http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
ALL_PROXY="http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
NO_PROXY="localhost,127.0.0.1,::1"

# /etc/systemd/system/my-agent.service.d/proxy.conf  (preferred for daemons)
[Service]
Environment="HTTP_PROXY=http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
Environment="HTTPS_PROXY=http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
Environment="NO_PROXY=localhost,127.0.0.1,::1"
Environment="SSL_CERT_FILE=/etc/ssl/certs/4keyless-ca.crt"

# curl — ~/.curlrc
proxy = "http://proxy.4keyless.io:8080"
proxy-header = "Proxy-Authorization: 4Keyless 4k_your_agent_key"
cacert = "/home/you/4keyless-ca.crt"

# wget — ~/.wgetrc
use_proxy = on
http_proxy = http://agent:4k_your_agent_key@proxy.4keyless.io:8080
https_proxy = http://agent:4k_your_agent_key@proxy.4keyless.io:8080

# git
git config --global http.proxy "http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
git config --global https.proxy "http://agent:4k_your_agent_key@proxy.4keyless.io:8080"

# apt (Debian/Ubuntu)
sudo tee /etc/apt/apt.conf.d/95fourkeyless <<'EOF'
Acquire::http::Proxy "http://agent:4k_your_agent_key@proxy.4keyless.io:8080";
Acquire::https::Proxy "http://agent:4k_your_agent_key@proxy.4keyless.io:8080";
EOF

curl -v --cacert ~/4keyless-ca.crt https://httpbin.org/ip

curl -v --proxy http://proxy.4keyless.io:8080 \
  --proxy-header "Proxy-Authorization: 4Keyless ${FKL_AGENT_KEY}" \
  --cacert ~/4keyless-ca.crt \
  https://httpbin.org/ip

Quickstart

Provision your first agent and route a request in six steps.

1. Sign in at https://admin.4keyless.io and complete MFA in Settings.
2. Create a Target System (REST API, Web App, GraphQL, Database, or MCP). A system can hold multiple domains.
3. Create a Credential in Vault and link it to the system.
4. Create an AI Agent and store the generated agent key securely.
5. Add a Policy binding the agent to the system (start with block, then open selected flows).
6. Install the CA, configure your client, and send your first request.

# First proxied request
curl --proxy http://proxy.4keyless.io:8080 \
  --proxy-header "Proxy-Authorization: 4Keyless <agent-key>" \
  --cacert 4keyless-ca.crt \
  https://api.github.com/zen

API Reference

Resources are managed in the Admin Panel and over REST under https://api.4keyless.io/api/v1 (workspace JWT). Each section below lists the resource, its REST endpoints, and configuration fields.

A target the agent reaches. Supports types REST API, Web App, GraphQL, Database, and MCP, each with one or more domains.

Fields

Secrets stored in Vault and linked to systems. 4Keyless injects them at request time so the agent never sees raw secret values.

• Group credentials with Credential Groups to map blueprint slots.
• Upstream MCP servers may use a Bearer token credential (see MCP Gateway).
• Rotate or revoke a credential without touching agent or policy config.

An AI identity authenticated to the proxy and MCP gateway via its agent key. See Authentication for header formats.

After rotating a key, update it in your AI runtime immediately — old keys stop authenticating right away.

Policies define what each agent may do against each system.

Recommended default: start with block, then move selected flows to allow or ask. MCP tool calls are matched per tool using the mcp_tool_name field.

Lets agents reach upstream MCP (Model Context Protocol) servers through the same auth, policy enforcement, and credential injection used by the HTTP proxy. Exposed publicly at https://mcp.4keyless.io/mcp.

Register an MCP system

1. In Systems, create a system of type MCP.
2. Set Transport (HTTP, SSE, or Stdio) and Server URL (e.g. https://mcp.notion.com/mcp).
3. Optionally link an Upstream Credential (Bearer token for the MCP server).
4. Open MCP Gateway and click Sync to discover tools.

Connection URL

Append ?system=<name-or-uuid> to scope to a single MCP system, or omit it to aggregate tools across every MCP system the agent can access. The ?system= value accepts a UUID or the system name (case-insensitive). When omitted, each tool is prefixed with the system slug to avoid clashes.

Examples

# List tools across every accessible MCP system
curl https://mcp.4keyless.io/mcp \
  -H "Proxy-Authorization: 4Keyless <agent-key>"

# Scope to a single system (name or UUID)
curl https://mcp.4keyless.io/mcp?system=MyMCPSystem \
  -H "Proxy-Authorization: 4Keyless <agent-key>"

# JSON-RPC request (POST)
curl -X POST https://mcp.4keyless.io/mcp?system=MyMCPSystem \
  -H "Proxy-Authorization: 4Keyless <agent-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Route outbound traffic through designated exit nodes — for IP rotation, geo-targeting, rate-limit handling, and network zoning. Every workspace includes one free catalog exit proxy; more are available as paid add-ons.

How egress is selected

1. Per-request header — X-4Keyless-Exit-Proxy: <id> (e.g. px_yd706g).
2. Plan default — used when the header is omitted, or when the ID is invalid/inactive (fallback; traffic does not leave directly from the 4Keyless proxy IP).

The header is stripped before forwarding upstream. Effective egress is recorded in Logs under exit_proxy (with requested_id and fallback on bad-header fallback). exec_script sandbox calls (http.get, http.post) use the same effective exit proxy as the main request.

Endpoints

Examples

# Default plan exit proxy (omit header)
curl --proxy http://proxy.4keyless.io:8080 \
  --proxy-header "Proxy-Authorization: 4Keyless <agent-key>" \
  --cacert 4keyless-ca.crt \
  https://api.github.com/zen

# Specific exit proxy for this request
curl --proxy http://proxy.4keyless.io:8080 \
  --proxy-header "Proxy-Authorization: 4Keyless <agent-key>" \
  -H "X-4Keyless-Exit-Proxy: px_yd706g" \
  --cacert 4keyless-ca.crt \
  https://example.com/

Global templates that provision a system, auth script, request/response actions, and access policies in one step, using verified configurations.

Install a blueprint

1. Open Marketplace in the left menu.
2. Select a blueprint and click Install.
3. Choose the target Agent Group and Credential Group.
4. Map required credential slots to Vault items.
5. Click install — system, auth script, actions, and policies are created instantly.

Upgrades

A new blueprint version shows an Update available badge. Upgrading updates script actions and domains automatically, rematerializing placeholders while preserving your credential mappings.

Tamper-proof audit records of every decision. Filter by agent, system, decision, and time window.

Errors

Proxy and gateway responses use standard HTTP status codes. The REST API returns { data, meta?, error? }.

Successful requests appear in Logs with the agent name and upstream decision.

Rate limits & plans

Every workspace starts on the Free plan (1 agent, 2 systems, 1 GB transfer/month, 14-day log retention). Paid plans add capacity, Script Actions (Starter+), ASK policies (Growth+), and longer retention. MFA and the MCP Gateway are included on all plans.

See the full feature comparison for limits per tier.

Daily operations

• Dashboard — monitor recent activity and key metrics.
• Logs — filter by agent, system, decision, and time window.
• Notifications — review and respond to approval requests.
• Scripts — manage script actions for custom request/response behavior.
• MCP Gateway — manage MCP systems, sync tools, monitor tool calls.
• Settings — manage MFA and workspace preferences.

Typical onboarding flow

1. Admin creates workspace users and enables MFA.
2. Operator creates exit proxies if IP rotation is required.
3. Operator installs a Marketplace blueprint (or registers systems, auth scripts, and policies manually).
4. Operator links credential slots securely to Vault.
5. Security owner customizes access policies and agent permissions.
6. AI client traffic is routed through the proxy or MCP gateway.
7. Team monitors tamper-proof logs and human-in-the-loop notifications daily.

Security best practices

• Enforce least privilege with roles (viewer, operator, admin).
• Rotate agent keys regularly or after any suspected leak.
• Use block as default and grant allow selectively.
• Keep high-risk systems behind ask with human approval.
• Review audit logs and notifications as part of daily operations.