Agent protocol

How agents authenticate, discover services, route requests through HTTPS_PROXY, and propose changes through Agent Vault.

Agent Vault agents follow a standard HTTP protocol to interact with the server. Agents handle this automatically — the instructions are embedded in every invite response and in the agent skill files. This page is a reference for understanding what happens under the hood.

Agents must never extract, log, or display credential values. They reference credentials by key name only.

Bearer token

Every request an agent makes to Agent Vault requires a bearer token. How the agent gets one depends on how it connects:

Method	How the agent gets a token
agent-vault vault run	Agent Vault sets AGENT_VAULT_SESSION_TOKEN on the child process automatically
Agent invite	Agent calls POST {invite_url} and receives an agent token

Both methods deliver the same core connection details:

Variable	Description
AGENT_VAULT_ADDR	Base URL of the Agent Vault server (e.g. http://127.0.0.1:14321)
AGENT_VAULT_SESSION_TOKEN	Bearer token for all Agent Vault requests

Session types

There are two session types:

• Vault-scoped sessions — created by agent-vault vault run. The vault is embedded in the session. No extra headers needed.
• Instance-level agent tokens — created via agent invites. The agent must include an X-Vault header on every vault-scoped request to select which vault to use.

The X-Vault header

Instance-level agent tokens must include X-Vault: {vault_name} on all vault-scoped requests (discover, proposals, credentials):

GET {AGENT_VAULT_ADDR}/discover
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}
X-Vault: my-vault

Agents created via agent-vault vault run do not need this header — the vault is embedded in the session token.

Discover services

Before making any proxied request, the agent calls /discover to learn which hosts have credentials configured in the vault.

GET {AGENT_VAULT_ADDR}/discover
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}
X-Vault: my-vault

The X-Vault header is required for instance-level agent tokens. Vault-scoped sessions (from vault run) can omit it.

Response

{
  "vault": "my-vault",
  "proxy_url": "http://127.0.0.1:14321/proxy",
  "services": [
    { "host": "api.stripe.com", "description": "Stripe API" },
    { "host": "*.github.com", "description": "GitHub API" }
  ],
  "available_credentials": ["GITHUB_TOKEN", "STRIPE_KEY"]
}

• services lists the hosts the agent can reach through Agent Vault (defined by the vault’s services). Requests to any other host go direct.
• available_credentials lists credential key names in the vault (values are never exposed). Agents use these to avoid creating duplicate slots in proposals.
• proxy_url is the fallback endpoint for clients that can’t honor HTTPS_PROXY. See Explicit proxy endpoint.

Route requests through HTTPS_PROXY

The canonical way for an agent to reach an upstream host is to call the real URL directly. agent-vault vault run pre-configures HTTPS_PROXY and the CA trust chain on the child process, so every standard HTTP client — curl, fetch, requests, axios, the Go stdlib, SDKs like stripe-node, CLIs like gh and stripe — transparently routes through the broker. Agent Vault intercepts the CONNECT, matches the target host against the vault’s services, and injects the stored credential into the auth header for that service. Other client headers (vendor headers like anthropic-version, tracing IDs, etc.) flow through unchanged — see Header forwarding for the precise rules.

GET https://api.stripe.com/v1/charges?limit=10

The agent writes this line unchanged. No URL rewriting. No Authorization header. No credential in the code.

Environment set by vault run

Variable	Purpose
HTTPS_PROXY	Points at the MITM listener (http://{token}:{vault}@host:14322)
NO_PROXY	localhost,127.0.0.1 — so agent-to-vault traffic skips the proxy
NODE_USE_ENV_PROXY	1 — enables Node.js v22.21+ built-in HTTPS_PROXY support for fetch() and https.get()
SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, DENO_CERT	Point standard HTTP libraries at the Agent Vault root CA so the proxied TLS handshake validates

HTTP_PROXY is intentionally not set. The MITM listener only handles HTTPS (CONNECT) and would 405 on plain http:// requests.

Explicit proxy endpoint (fallback)

For clients that can’t honor HTTPS_PROXY — HTTP/2-terminating edges, constrained runtimes, sandboxes without CA-mounting — Agent Vault exposes an explicit endpoint:

{AGENT_VAULT_ADDR}/proxy/{target_host}/{path}[?query]
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}

Rewrite the upstream URL to this shape and Agent Vault applies the same credential-injection logic — strips the agent’s Authorization header, attaches credentials from the vault’s services, forwards over HTTPS.

GET

GET http://127.0.0.1:14321/proxy/api.stripe.com/v1/charges?limit=10
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}

Propose changes

When an agent needs access to a service that is not in the vault’s services, it creates a proposal. Each proposal bundles services (host access) and credential slots (credentials the human provides at approval time).

POST {AGENT_VAULT_ADDR}/v1/proposals
Authorization: Bearer {AGENT_VAULT_SESSION_TOKEN}
Content-Type: application/json

{
  "services": [
    {
      "action": "set",
      "host": "api.stripe.com",
      "description": "Stripe API",
      "auth": { "type": "bearer", "token": "STRIPE_KEY" }
    }
  ],
  "credentials": [
    {
      "action": "set",
      "key": "STRIPE_KEY",
      "description": "Stripe API key",
      "obtain": "https://dashboard.stripe.com/apikeys",
      "obtain_instructions": "Developers > API Keys > Reveal test key"
    }
  ],
  "message": "Need Stripe API key for billing feature",
  "user_message": "I need access to your Stripe account to build the checkout page."
}

The response includes an approval_url that the agent presents to the user:

Response (201)

{
  "id": 1,
  "status": "pending",
  "vault": "default",
  "approval_url": "http://localhost:14321/approve/1?token=av_appr_...",
  "message": "Proposal created. Approve here: http://localhost:14321/approve/1?token=av_appr_..."
}

The agent then polls GET /v1/proposals/{id} until the status changes from pending (every 3s for the first 30s, then every 10s). Once applied, the agent retries its original request.

Every credential key referenced in a service’s auth config must resolve to either a credential slot in the same proposal or an existing credential in available_credentials. Otherwise the request returns 400.

See Proposals for the full proposal lifecycle, including storing credentials back and removing access.

Error handling

Status	Meaning	What the agent does
401	Invalid or expired token	Re-check AGENT_VAULT_SESSION_TOKEN. Contact operator for a new token or rotation.
403 forbidden	Host not allowed	Create a proposal to request access. The response includes a proposal_hint.
403 service_disabled	Host is configured but disabled	Surface to the user — don’t create a duplicate proposal.
429	Rate limited	Respect the Retry-After header. The MITM and /proxy paths share one budget.
502	Missing credential or upstream unreachable	Tell the user a credential may need to be added.

Security constraints

• Never extract, log, or display credential values
• Never hardcode tokens. Always read from AGENT_VAULT_SESSION_TOKEN.
• Only reach hosts returned by /discover. For unlisted hosts, create a proposal.
• If a credential_not_found error occurs, inform the user which key is missing.