Proxy API

All endpoints except /health require the X-AgentSec-Key header for authentication.

POST /forward

The core proxy endpoint. Authenticates the agent, evaluates policy, requests approval if needed, injects credentials, forwards the request, and sanitizes the response.

Unified Mode (Recommended)

Reference a credential by name. The proxy handles routing and auth injection automatically.

Headers:

Header	Required	Description
`X-AgentSec-Key`	yes	Agent API key
`X-AgentSec-Credential`	yes	Credential name from config
`X-AgentSec-Target`	yes	Target API URL (or path if `relative_target: true`)
`X-AgentSec-Method`	no	HTTP method to use upstream (default: POST)

Example — auto-approved GET:

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $MY_KEY" \
  -H "X-AgentSec-Credential: slack" \
  -H "X-AgentSec-Target: https://slack.com/api/conversations.list" \
  -H "X-AgentSec-Method: GET"

Example — POST requiring approval:

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $MY_KEY" \
  -H "X-AgentSec-Credential: slack" \
  -H "X-AgentSec-Target: https://slack.com/api/chat.postMessage" \
  -H "X-AgentSec-Method: POST" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C123456", "text": "Hello from my agent"}'

The request blocks until approved/denied in Telegram or times out (default 5 minutes).

Example — sidecar with relative target:

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $MY_KEY" \
  -H "X-AgentSec-Credential: telegram" \
  -H "X-AgentSec-Target: /sendMessage" \
  -H "X-AgentSec-Method: POST" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "123", "text": "Hello"}'

Legacy Placeholder Mode

Use <CREDENTIAL:name> placeholders in headers or body. The proxy validates placeholder positions, then substitutes real values after approval.

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $MY_KEY" \
  -H "X-AgentSec-Target: https://api.openai.com/v1/chat/completions" \
  -H "Authorization: Bearer <CREDENTIAL:openai-key>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}]}'

Placeholders are only allowed in auth-related positions. See How It Works for details.

Error Responses

Status	Meaning
400	Invalid request (missing headers, placeholder in non-auth position)
401	Invalid or missing `X-AgentSec-Key`
403	Credential not whitelisted for this agent, or approval denied
429	Rate limit exceeded
502	Upstream API error
504	Approval timed out

All errors return JSON:

{"error": "description of what went wrong"}

GET /agent/services

Returns available services for the authenticated agent with approval requirements and usage examples.

curl http://localhost:3100/agent/services \
  -H "X-AgentSec-Key: $MY_KEY"

Response:

{
  "agent_id": "my-agent",
  "services": {
    "slack": {
      "description": "Slack API",
      "reads_auto_approved": true,
      "writes_need_approval": true,
      "target_base": "https://slack.com/api"
    }
  },
  "usage": {
    "method": "POST /forward",
    "headers": {
      "X-AgentSec-Key": "<your-key>",
      "X-AgentSec-Credential": "<service-name>",
      "X-AgentSec-Target": "<api-url-or-path>",
      "X-AgentSec-Method": "GET|POST|PUT|PATCH|DELETE"
    }
  }
}

Internal details (sidecar URLs, connector types) are hidden from agents.

GET /agent/logs

Returns recent audit log entries for the authenticated agent.

curl "http://localhost:3100/agent/logs?limit=5" \
  -H "X-AgentSec-Key: $MY_KEY"

Query parameters:

Param	Default	Max	Description
`limit`	20	100	Number of entries to return

Response:

{
  "agent_id": "my-agent",
  "count": 1,
  "entries": [
    {
      "request_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "my-agent",
      "credential_names": ["slack"],
      "target_url": "https://slack.com/api/conversations.list",
      "method": "GET",
      "approval_status": "AutoApproved",
      "upstream_status": 200,
      "total_latency_ms": 145,
      "approval_latency_ms": 0,
      "upstream_latency_ms": 120,
      "response_sanitized": false,
      "timestamp": "2026-03-30T14:22:15.123Z"
    }
  ]
}

GET /agent/config

Returns the credential list and policies for the authenticated agent.

curl http://localhost:3100/agent/config \
  -H "X-AgentSec-Key: $MY_KEY"

GET /health

Health check endpoint. No authentication required.

curl http://localhost:3100/health

Returns 200 OK when the proxy is running.

Configuration CLI Reference