credential-proxy.md

Credential Proxy

Date: 2026-06-28

The credential proxy is the ADR-028 HTTP/API delivery backend for workloads that can call a broker instead of receiving an upstream secret. Workloads send a credential lease reference, session scope, and target HTTP request to management. Management validates the lease and proxy policy, injects the upstream credential only on the outbound proxy hop, and returns a redacted response.

This backend is for web/API style integrations. Provider CLIs that require local files, browser state, SSH private keys, or final-child environment values still use the file/env materialization paths documented in docs/workload-credentials-and-autostart.md.

Endpoint

POST /api/v2/credential-proxy/http
Content-Type: application/json

Request body:

{
  "lease_id": "lease_...",
  "agent_id": "agent-01",
  "instance_id": "agent-01",
  "session_id": "session-01",
  "method": "GET",
  "url": "https://api.example.test/v1/models",
  "headers": {
    "accept": "application/json"
  },
  "body": null
}

Response body:

{
  "status": 200,
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"ok\":true}"
}

The response status is the upstream HTTP status. Proxy authorization failures return management API status codes such as 403 for denied policy, 404 for missing leases, or 429 when an active lease exceeds its configured proxy rate limit. Rate-limit responses include Retry-After.

Lease Policy

POST /api/v2/credentials/{id}/leases may include proxy_policy:

{
  "agent_id": "agent-01",
  "instance_id": "agent-01",
  "session_id": "session-01",
  "provider": "github",
  "allowed_use": "api.proxy",
  "ttl_seconds": 900,
  "proxy_policy": {
    "allowed_hosts": ["api.github.com"],
    "allowed_path_prefixes": ["/repos/example/"],
    "allowed_methods": ["GET", "POST"],
    "allowed_headers": ["accept", "content-type"],
    "injected_header": {
      "name": "authorization",
      "value_prefix": "Bearer "
    },
    "rate_limit_per_minute": 60
  }
}

Current enforcement:

Policy field	Enforcement
allowed_hosts	Exact host, exact host:port, or *.example.test suffix match.
allowed_path_prefixes	Request path must start with one configured prefix when non-empty.
allowed_methods	Request method must match when non-empty.
allowed_headers	Workload-supplied headers must be explicitly allowed.
injected_header	Proxy overwrites that header with <value_prefix><secret>. Defaults to Authorization: Bearer <secret>.
rate_limit_per_minute	Enforced per active lease_id plus agent_id/instance_id/session_id scope. Counters naturally expire with the lease and are checked only after active-lease validation succeeds.

The lease id is not a bearer credential by itself. The proxy also requires the matching agent_id, instance_id, and session_id, and the lease must be active and unexpired.

Rate-limit accounting is deliberately after active-lease and scope validation. Revoked, expired, missing, or wrong-session leases are denied as lease failures, not as rate-limit events.

Redaction

Credential values are not returned by credential metadata APIs, lease APIs, or the proxy request path. The proxy redacts occurrences of the injected secret from upstream response headers and body before returning JSON to the workload. Denied and rate-limited proxy responses contain only management error text and retry metadata; they do not include upstream credential values.

Operators should still treat proxy responses as sensitive workload data. The proxy does not inspect provider-specific response formats, does not stream binary responses, and currently caps the upstream response body at 1 MiB.

Runtime Use

Local agents can call the management listener on loopback or through the local Unix-socket HTTP path where configured. Containers and VMs should receive only the proxy URL plus lease metadata scoped to the managed session. They should not receive upstream API keys, bearer tokens, cookies, or signed URLs when the provider can be mediated through this endpoint.

Network egress controls remain important. If a workload can reach the upstream service directly through another route, the proxy prevents managed secret delivery but does not by itself prove that all traffic used the proxy.