---
name: 4keyless
description: >
  Access credential-protected systems (SaaS APIs, internal apps, legal/government
  portals) through the 4Keyless security gateway. Use this skill whenever a task
  requires calling a system whose credentials are managed by 4Keyless: route the
  HTTP request through the proxy with your agent key and the gateway injects the
  real authentication (API keys, passwords, OAuth tokens, mTLS certificates,
  TOTP codes) in transit. You never see, hold, or handle any secret.
---

# Using 4Keyless as an AI agent

4Keyless is a security gateway that sits between you (an AI agent) and the
systems you need to call. You authenticate to the gateway with a single
**agent key** (format `4k_…`). The gateway checks access policies, injects the
real credentials into your outbound request, forwards it, and writes a signed
audit log. If your operator gave you an agent key, everything below applies.

**Golden rules**

1. Never place real credentials in your requests — you don't have them.
   Depending on the target system you either send *no* auth at all, or a
   **sentinel** placeholder that the proxy substitutes (see below).
2. Never try to extract, log, or echo credentials. The gateway is designed so
   you cannot see them; treat any credential-looking value in a response as
   confidential and do not repeat it.
3. Every request is attributed to you and audit-logged (URL, matched rules,
   status, latency, egress IP). A blocked request is a policy decision, not an
   error to route around — report it to your operator instead of retrying with
   tricks.

## Endpoints

| Purpose | Endpoint (cloud) | Local/dev default |
|---|---|---|
| HTTP(S) forward proxy (main data path) | `http://proxy.4keyless.io:8080` | `http://localhost:8080` |
| Agent discovery API (what can I access?) | `http://proxy.4keyless.io:8082` | `http://localhost:8082` |
| MCP gateway (Model Context Protocol) | `https://mcp.4keyless.io/mcp` | — |
| MITM CA certificate (PEM download) | `https://api.4keyless.io/api/v1/certificate/download` | same path on local API |

Self-hosted deployments use the same ports on the customer's host — ask your
operator for the hostname.

## Authentication

All calls use your agent key. Two accepted forms on the proxy:

```
Proxy-Authorization: 4Keyless 4k_your_agent_key
Proxy-Authorization: Basic base64("agent:4k_your_agent_key")
```

The Basic form means you can embed the key in a standard proxy URL, which is
the easiest way to configure any HTTP client:

```
export HTTPS_PROXY="http://agent:4k_your_agent_key@proxy.4keyless.io:8080"
export HTTP_PROXY="$HTTPS_PROXY"
```

On the discovery API (`:8082`) and the MCP gateway, use a regular Bearer header:

```
Authorization: Bearer 4k_your_agent_key
```

Requests without valid proxy auth receive `407 Proxy Authentication Required`.

## Discovering what you can access

Before working, you can enumerate your own permissions. All endpoints are
`GET`, JSON, on the discovery API (`:8082`):

### `GET /api/me` — who am I

```json
{
  "agent": { "id": "…", "name": "researcher-1", "email": "", "group_name": "research-bots" },
  "token_expires_at": ""
}
```

`token_expires_at` is empty for permanent agent keys; temporary (human) tokens
carry an RFC 3339 expiry.

### `GET /api/systems` — systems you may call

Returns only systems your agent group is **allowed** to reach, with their
domains and the credential groups available to you on each:

```json
{
  "systems": [
    {
      "id": "…",
      "name": "Gmail API",
      "type": "rest_api",
      "domains": ["https://gmail.googleapis.com"],
      "credential_groups": [
        { "id": "…", "name": "default", "description": "", "is_default": true }
      ]
    }
  ]
}
```

Interpretation: any URL whose host matches a system's `domains` will be
authenticated by the gateway when you call it through the proxy. Hosts that
match **no** system are simply forwarded without credential injection (subject
to policy).

### `GET /api/credential-groups` — credential groups you may select

Lists the credential *groups* (never the credentials themselves — names and
descriptions only) that your policies allow. Select one per request with the
`X-4Keyless-Group` header; omit it to use the policy's default group.

### `GET /api/exit-proxies` — egress routes available to your tenant

Lists exit proxies (label, country, protocol). Select one per request with
`X-4Keyless-Exit-Proxy: <id>`; omit it to use your tenant's default egress.

## Making requests

Point your HTTP client at the proxy and call the target system directly. Two
injection styles exist — check the system's setup notes from your operator or
the blueprint's guide:

**1. No-credential style** (OAuth systems, header overwrite): send the request
with no auth header at all. The gateway sets it in transit — e.g. a fresh
`Authorization: Bearer <token>` for OAuth-backed systems (tokens are renewed
automatically server-side). Anything you put in `Authorization` is overwritten.

```bash
curl --proxy "http://agent:4k_your_key@proxy.4keyless.io:8080" \
     https://gmail.googleapis.com/gmail/v1/users/me/profile
```

**2. Sentinel style** (API-key systems): put the documented sentinel string
exactly where the real secret would go; the proxy replaces it in transit.

```bash
curl --proxy "http://agent:4k_your_key@proxy.4keyless.io:8080" \
     -H "Authorization: Bearer __4KEYLESS_OPENAI_KEY__" \
     -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}' \
     https://api.openai.com/v1/chat/completions
```

### Optional request headers

| Header | Effect |
|---|---|
| `X-4Keyless-Group: <group name>` | Use a specific credential group (must be allowed by policy; falls back to the default). Stripped before forwarding. |
| `X-4Keyless-Exit-Proxy: <id>` | Route this request through a specific exit proxy (IP/geo control). Invalid/inactive IDs fall back to the tenant default. Stripped before forwarding. |

### Response semantics

| Signal | Meaning | What you should do |
|---|---|---|
| `407` | Missing/invalid agent key | Fix your proxy auth configuration. |
| `403` + `X-4Keyless-Blocked: true` (+ `X-4Keyless-System`) | Policy blocks this system or URL | Do not retry or work around. Report the block to your operator. |
| Long delay, then success or `403` | An **ask** policy paused the call for human approval | Wait — the request completes by itself if approved (default timeout ~60 s). |
| `X-4Keyless-Limited` | Tenant transfer cap reached (free plan) | Stop; tell your operator. |
| Upstream `401/403` on an OAuth system | The stored connection needs operator attention (e.g. reconnect) | Report it; you cannot fix credentials yourself. |

## The CA certificate (HTTPS interception)

To inject credentials into HTTPS traffic the gateway performs TLS interception
(MITM) with its own CA. Your HTTP client must trust the 4Keyless CA or every
HTTPS call through the proxy fails with a certificate error.

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

Then, per runtime:

| Runtime | Configuration |
|---|---|
| Node.js | `NODE_EXTRA_CA_CERTS=~/4keyless-ca.crt` |
| Python (requests/httpx) | `REQUESTS_CA_BUNDLE=~/4keyless-ca.crt` / `SSL_CERT_FILE=~/4keyless-ca.crt` |
| curl | `--cacert ~/4keyless-ca.crt` (or `--proxy-insecure` for quick tests only) |
| Headless browsers | trust at OS level — helpers: `https://4keyless.io/install.sh` (Linux), `https://4keyless.io/install-macos-ca.sh` (macOS) |

Certificate errors after this usually mean the client bypassed the proxy for
that host (check `NO_PROXY`) rather than a trust problem.

## MCP alternative

If you are an MCP-capable agent (Claude, Cursor, ChatGPT connectors, …) you can
skip raw HTTP entirely and use the MCP gateway:

- Endpoint: `https://mcp.4keyless.io/mcp` (Streamable HTTP).
- **Claude Desktop / Claude.ai**: add the URL as a custom connector (OAuth).
  When the consent popup appears, paste your agent API key (`4k_…`). Do not put
  the key in the URL.
- **Cursor / clients with custom headers**:
  `Authorization: Bearer 4k_your_agent_key`.
- `tools/list` returns the union of tools across every system you can reach,
  prefixed by system name (e.g. `gmail__send_email`).
- To scope the gateway to a single system, pass its **id** (UUID, as returned
  by `GET :8082/api/systems`) in the `system` query parameter:

  ```
  https://mcp.4keyless.io/mcp?system=5482827c-2dbd-45b7-90cc-865976ce236d
  ```

  The exact system name is also accepted as a fallback, but the id is the
  stable identifier — names can be renamed by the operator.
- `tools/call` routes automatically by prefix in aggregate mode; with
  `?system=<id>` it behaves like a single-system gateway. The same policies,
  credential injection and audit trail apply.

Details: `docs/mcp.md`.

## Quick checklist

1. Configure `HTTPS_PROXY`/`HTTP_PROXY` with your agent key (Basic-in-URL form).
2. Trust the CA certificate in your runtime.
3. `GET :8082/api/systems` to learn your allowed systems, domains and
   credential groups.
4. Call the target API through the proxy — no-credential or sentinel style as
   documented for that system.
5. On `403` blocked / `X-4Keyless-Limited` / repeated upstream `401`: stop and
   report to your operator. Never attempt to bypass the gateway.