POST /proxy

Forward agent requests through the secure gateway with credential injection

Endpoint

POST /proxy

Main proxy endpoint for agents to forward requests through the gateway. Handles authentication, validation, credential injection, risk assessment, and idempotency.

Authentication

Requires Agent-Key header with valid agent API key.

Agent-Key: your-agent-key-here

Request Headers

Agent-Key · string · required

Agent API key for authentication

Idempotency-Key · string

Idempotency key for request deduplication. Required for POST and PATCH requests. Header takes precedence over body field if both are provided.

Request Body

targetUrl · string · required

Target URL to forward the request to. Must match a registered service’s baseUrl and pass SSRF validation.

Example: https://api.github.com/repos/owner/repo/issues

method · string · required

HTTP method for the request.

Allowed values: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

headers · object · default: "{}"

Request headers to forward to the target service. Do not include Authorization or credential headers - these are injected automatically.

Example: {"Content-Type": "application/json", "Accept": "application/json"}

body · string

Request body as a JSON string. Nullable for methods that don’t require a body.

Example: "{\"title\": \"Bug report\", \"body\": \"Description\"}"

intent · string · required

Human-readable description of what this request is attempting to do. Used for risk assessment and audit logging.

Constraints: 1-500 characters

Example: "Create a new GitHub issue for bug report"

idempotencyKey · string

Idempotency key for request deduplication. Required for POST and PATCH requests. Can be provided via header instead.

Constraints: 1-255 characters

Example: "issue-creation-20260303-001"

Response

Success Response (200 OK)

Request was successfully forwarded and completed.

status · number

HTTP status code from the target service

headers · object

Response headers from the target service, including:

• Content-Type: Preserved from target response
• X-Proxy-Status: Always "forwarded" for successful requests
• X-Idempotency-Status: "processed" if idempotency key was used

body · string

Response body from the target service (as received)

Risk-Blocked Response (428 Precondition Required)

Request was blocked due to high risk score and requires human approval.

error · string

Error message: "Request requires human approval"

action_id · string

Unique identifier for the approval queue entry. Use this to poll status via GET /status/:actionId.

risk_score · number

Risk assessment score (0-100) that triggered the block.

risk_explanation · string

Human-readable explanation of why the request was flagged as risky.

status_url · string

URL to poll for approval status: /status/:actionId

Error Responses

401 Unauthorized

Invalid or missing Agent-Key header

400 Bad Request

• Invalid request body schema
• Invalid URL format
• Missing required idempotencyKey for POST/PATCH
• Invalid HTTP method

403 Forbidden

• Target URL hostname doesn’t match service baseUrl (SSRF prevention)
• Target URL path doesn’t start with service baseUrl path
• Access to private IP ranges blocked
• Access to localhost blocked

404 Not Found

No service found matching target URL, or agent doesn’t have access to the service

409 Conflict

Request with this idempotency key is already being processed

413 Payload Too Large

Response size exceeds 10MB limit

428 Precondition Required

Request blocked by risk assessment - see response body for action_id to track approval

500 Internal Server Error

• No credentials found for service
• Failed to decrypt credentials
• Unsupported authentication type

502 Bad Gateway

Failed to forward request to target service

504 Gateway Timeout

Request timeout (30 second limit exceeded)

Examples

Simple GET Request

curl -X POST https://api.gaiterguard.com/proxy \
  -H "Agent-Key: your-agent-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.github.com/repos/owner/repo/issues",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    },
    "intent": "List all issues in the repository"
  }'

curl -X POST https://api.gaiterguard.com/proxy \
  -H "Agent-Key: your-agent-key-here" \
  -H "Idempotency-Key: issue-creation-20260303-001" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.github.com/repos/owner/repo/issues",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "body": "{\"title\": \"Bug report\", \"body\": \"Description\"}",
    "intent": "Create a new GitHub issue for bug report"
  }'

curl -X POST https://api.gaiterguard.com/proxy \
  -H "Agent-Key: your-agent-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUrl": "https://api.stripe.com/v1/charges",
    "method": "POST",
    "headers": {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    "body": "amount=2000&currency=usd&source=tok_visa",
    "intent": "Create a $20 charge for customer order",
    "idempotencyKey": "charge-order-12345"
  }'

{
  "status": 201,
  "headers": {
    "Content-Type": "application/json",
    "X-Proxy-Status": "forwarded",
    "X-Idempotency-Status": "processed"
  },
  "body": "{\"id\": 123, \"title\": \"Bug report\", \"state\": \"open\"}"
}

{
  "error": "Request requires human approval",
  "action_id": "act_7f8e9d0c1b2a3456",
  "risk_score": 85,
  "risk_explanation": "DELETE request to production database endpoint with broad scope",
  "status_url": "/status/act_7f8e9d0c1b2a3456"
}

{
  "error": "No service found matching target URL or agent does not have access"
}

Request Flow

1. Authentication - Validate Agent-Key header
2. Schema Validation - Validate request body against schema
3. Idempotency Check - Check for cached response (if key provided)
4. Service Resolution - Find matching service and verify agent access
5. SSRF Validation - Validate target URL against service baseUrl
6. Risk Assessment - Evaluate request risk score
7. Credential Injection - Inject service credentials based on auth type
8. Forward Request - Send request to target service (30s timeout, 10MB limit)
9. Cache Response - Store response for idempotency (if key provided)
10. Return Response - Return target service response with proxy metadata

SSRF Protection

The gateway implements multiple layers of SSRF protection:

• Hostname matching: Target hostname must match service baseUrl hostname
• Path prefix validation: Target path must start with service baseUrl path
• Private IP blocking: Blocks 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x, ::1, fc00:, fe80:
• Localhost blocking: Blocks localhost hostname
• Protocol restriction: Only http:// and https:// allowed

Idempotency Behavior

• Required for POST and PATCH methods
• Can be provided via Idempotency-Key header or idempotencyKey body field
• Header takes precedence if both are provided
• Cached responses are returned immediately (status 200)
• Requests in-flight return 409 Conflict
• Cache is scoped to agent + key + request hash (method:url:body)