Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shashank-H/gaiter-gaurd/llms.txt

Use this file to discover all available pages before exploring further.

​
Request Headers

​
Authentication Headers

​
Agent-Key

Required for: All agent-facing proxy endpoints (POST /proxy, POST /proxy/execute/:actionId) 
Agent-Key: agt_1234567890abcdef1234567890abcdef1234567890abcdef12
  • Format: Must start with agt_ prefix followed by alphanumeric string
  • Validation: Checked in middleware/auth.ts:74
  • Usage: SHA-256 hashed and matched against stored keyHash in the agents table
  • Security: Agent key is hashed using SHA-256 before database lookup to prevent plaintext storage
Agent keys starting with any prefix other than agt_ will be rejected with a 401 error.
Error responses:
  • Missing header: 401 - Missing Agent-Key header
  • Invalid format: 401 - Invalid Agent-Key format
  • Invalid key: 401 - Invalid Agent-Key
  • Revoked key: 401 - Agent key has been revoked

​
Authorization

Required for: Dashboard and user-facing endpoints (agents, services, etc.) 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  • Format: Must use Bearer token authentication
  • Validation: Checked in middleware/auth.ts:31
  • Token Type: JWT access token issued by /auth/login or /auth/refresh
  • Expiration: Tokens expire after a configured duration (verify via JWT payload)
Error responses:
  • Missing header: 401 - Missing authorization header
  • Invalid format: 401 - Invalid authorization header format
  • Missing token: 401 - Missing token
  • Invalid/expired token: 401 - Invalid or expired token
The Authorization header is automatically stripped from requests before storing them in the approval queue to prevent credential leakage. See services/proxy.service.ts:409.

​
Idempotency Headers

​
Idempotency-Key

Required for: POST and PATCH requests to /proxy Optional for: GET, PUT, DELETE, HEAD, OPTIONS requests 
Idempotency-Key: order-12345-retry-1
  • Format: String, 1-255 characters
  • Scope: Per-agent (different agents can use the same key)
  • Behavior: See Idempotency for full details
  • TTL: Idempotency keys expire after 24 hours
  • Precedence: Header value takes precedence over idempotencyKey field in request body
Implementation: Extracted in routes/proxy.ts:48 
const idempotencyKeyHeader = req.headers.get('Idempotency-Key');
if (idempotencyKeyHeader) {
  data.idempotencyKey = idempotencyKeyHeader;
}
POST and PATCH requests without an Idempotency-Key will be rejected with a 400 validation error.

​
Content Type Headers

​
Content-Type

Required for: All requests with a request body 
Content-Type: application/json
  • Supported: application/json for GaiterGuard API endpoints
  • Proxy Requests: Any Content-Type supported by the target service (passed through)
  • Validation: JSON parsing errors return 400 with Invalid JSON in request body

​
Response Headers

​
Standard Headers

​
Content-Type

All responses include a Content-Type header: 
Content-Type: application/json
For proxied requests, the Content-Type from the target service is passed through: 
// From routes/proxy.ts:69
const contentType = targetHeaders['content-type'] || 'application/json';
responseHeaders.set('Content-Type', contentType);

​
Proxy Metadata Headers

These headers are added by the GaiterGuard gateway to proxied responses.

​
X-Proxy-Status

Indicates how the request was processed: 
X-Proxy-Status: forwarded
Possible values:
  • forwarded - Request was forwarded to target service and response returned
  • executed-approved - Request was executed after human approval via /proxy/execute/:actionId
Implementation: Set in routes/proxy.ts:73 and routes/proxy.ts:218

​
X-Idempotency-Status

Indicates idempotency key usage (only present if idempotency key was provided): 
X-Idempotency-Status: processed
Possible values:
  • processed - Request used an idempotency key (may be cache hit or new request)
The current implementation marks all idempotency-keyed requests as processed. Future versions may distinguish between hit (cached) and miss (new request).
Implementation: Set in routes/proxy.ts:81 
if (data.idempotencyKey) {
  responseHeaders.set('X-Idempotency-Status', 'processed');
}

​
Header Handling in Proxy Requests

​
Credential Injection

When forwarding requests to target services, GaiterGuard automatically injects authentication credentials based on the service’s authType:
Auth TypeHeader AddedSource
bearerAuthorization: Bearer {token}credentials.token
api_keyX-API-Key: {api_key} or custom headercredentials.api_key or custom key
basicAuthorization: Basic {base64(user:pass)}credentials.username, credentials.password
oauth2Authorization: Bearer {access_token}credentials.access_token
Implementation: See services/proxy.service.ts:212

​
Header Stripping for Security

When storing requests in the approval queue, sensitive headers are stripped: 
// From services/proxy.service.ts:408
const safeHeaders = { ...data.headers };
delete safeHeaders['Authorization'];
delete safeHeaders['authorization'];
delete safeHeaders['Agent-Key'];
delete safeHeaders['agent-key'];
Credentials are re-injected fresh from the encrypted vault when executing approved requests.

​
SSRF Prevention

GaiterGuard implements strict header and URL validation to prevent SSRF attacks:
  • Blocks requests to private IP ranges: 127.x, 10.x, 172.16-31.x, 192.168.x, 169.254.x
  • Blocks IPv6 loopback: ::1, fc00:, fe80:
  • Blocks localhost hostnames
  • Only allows http:// and https:// protocols
  • Validates target URL matches service baseUrl
Implementation: See services/proxy.service.ts:92

​
Header Examples

​
Agent Proxy Request

POST /proxy HTTP/1.1
Host: api.gaiterguard.com
Agent-Key: agt_1234567890abcdef1234567890abcdef1234567890abcdef12
Idempotency-Key: user-create-001
Content-Type: application/json

{
  "targetUrl": "https://api.example.com/v1/users",
  "method": "POST",
  "headers": {
    "Accept": "application/json"
  },
  "body": "{\"name\":\"John\"}",
  "intent": "Create new user"
}

​
Dashboard Request

GET /agents HTTP/1.1
Host: api.gaiterguard.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/json

​
Proxied Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Proxy-Status: forwarded
X-Idempotency-Status: processed

{"id": 123, "name": "John"}

​
Execute Approved Request

POST /proxy/execute/a1b2c3d4-e5f6-7890-abcd-ef1234567890 HTTP/1.1
Host: api.gaiterguard.com
Agent-Key: agt_1234567890abcdef1234567890abcdef1234567890abcdef12

HTTP/1.1 200 OK
Content-Type: application/json
X-Proxy-Status: executed-approved

{"status": "deleted"}

Build docs developers (and LLMs) love

Get started for freeTalk to us