Skip to main content

​
What is Gateway?

Sigilum Gateway is a local reverse-proxy service that enforces Sigilum signed-auth and approved-claim checks before forwarding requests to third-party APIs with connector-managed credentials. Gateway validates incoming requests through a multi-stage authorization pipeline:
  1. Signature verification - Validates RFC 9421 HTTP Message Signatures
  2. Nonce replay protection - Prevents request replay attacks
  3. Claim validation - Confirms caller is approved for the requested service
  4. Upstream forwarding - Routes to configured connectors with credential injection

​
Architecture

Gateway operates as a local, single-instance service with:
  • BadgerDB storage for encrypted connector secrets
  • In-memory nonce cache for replay protection (process-local)
  • Claims cache synchronized with Sigilum API approved claims feed
  • MCP runtime for Model Context Protocol connections with discovery and tool filtering
Gateway is designed for local operation only. Nonce replay protection is process-local and resets on restart. For production multi-instance deployments, additional coordination is required.

​
API Surface

The Gateway API is organized into four functional areas:

​
Health & Metrics

  • GET /health - Overall health status
  • GET /health/live - Liveness probe
  • GET /health/ready - Readiness probe with dependency checks
  • GET /metrics - Prometheus metrics (admin access policy enforced)

​
Proxy Runtime

  • /{method} /proxy/{connection_id}/{path} - HTTP proxy with signature verification
  • /{method} /slack/{path} - Slack-specific alias (maps to slack-proxy connection)
See Proxy Endpoints for details.

​
MCP Runtime

  • GET /mcp/{connection_id}/tools - List filtered MCP tools
  • GET /mcp/{connection_id}/tools/{tool}/explain - Explain tool policy decision
  • POST /mcp/{connection_id}/tools/{tool}/call - Execute MCP tool
See MCP Runtime Endpoints for details.

​
Admin

  • Connection CRUD: GET/POST/PATCH/DELETE /api/admin/connections
  • Connection operations: /api/admin/connections/{id}/test, /api/admin/connections/{id}/rotate, /api/admin/connections/{id}/discover
  • Shared credentials: GET/POST/DELETE /api/admin/credential-variables
  • Service catalog: GET/PUT /api/admin/service-catalog
See Admin Endpoints for details.

​
Request Flow (Proxy)

When a client sends a signed request to a proxy endpoint:

​
Required Signature Headers

All proxy and MCP runtime requests require these signed headers:
​
signature-input
string
required
RFC 9421 Signature-Input header defining signed components and parameters
​
signature
string
required
RFC 9421 Signature header containing the cryptographic signature
​
sigilum-namespace
string
required
Sigilum namespace identifier for the requesting organization
​
sigilum-subject
string
required
Stable requester identifier within the namespace (user ID, employee ID, or principal)
​
sigilum-agent-key
string
required
Base64-encoded public key of the signing agent
​
sigilum-agent-cert
string
required
Agent certificate for signature verification

​
Error Envelope

All error responses use a consistent JSON structure:
​
error
string
required
Human-readable error summary
​
code
string
Stable machine-readable error code (see taxonomy below)
​
request_id
string
Correlation ID for logs and traces
​
timestamp
string
RFC3339 UTC timestamp of the error
​
docs_url
string
Reference URL for error remediation documentation

​
Example Error Response

{
  "error": "replay detected",
  "code": "AUTH_REPLAY_DETECTED",
  "request_id": "req_abc123",
  "timestamp": "2026-03-04T10:30:00Z",
  "docs_url": "https://docs.sigilum.id/gateway-errors#AUTH_REPLAY_DETECTED"
}

​
Auth Failure Code Taxonomy

Gateway returns deterministic auth failure codes for client error handling:
CodeDescriptionHTTP Status
AUTH_HEADERS_INVALIDDuplicate or malformed signed headers403
AUTH_SIGNATURE_INVALIDRFC 9421 signature verification failed403
AUTH_SIGNED_COMPONENTS_INVALIDSigned component list doesn’t match required profile403
AUTH_IDENTITY_INVALIDMissing or invalid Sigilum identity headers403
AUTH_NONCE_INVALIDSignature nonce missing or malformed403
AUTH_REPLAY_DETECTEDNonce already seen within replay window403
AUTH_CLAIMS_UNAVAILABLEGateway claim cache is unavailable503
AUTH_CLAIMS_LOOKUP_FAILEDClaim cache lookup failed500
AUTH_CLAIM_REQUIREDCaller not approved for requested service403
AUTH_CLAIM_SUBMIT_RATE_LIMITEDAuto-claim registration temporarily rate-limited429
AUTH_FORBIDDENGeneric auth denial fallback403
Clients should implement specific handling for AUTH_REPLAY_DETECTED (retry with new nonce) and AUTH_CLAIM_REQUIRED (initiate approval flow).

​
Protocol Support

Gateway supports two connection protocols:

​
HTTP Protocol (protocol: "http")

  • Request path: /proxy/{connection_id}/{path}
  • Requires upstream auth secret configuration
  • Supports auth modes: bearer, header_key, query_param

​
MCP Protocol (protocol: "mcp")

  • Runtime paths: /mcp/{connection_id}/tools, /mcp/{connection_id}/tools/{tool}/call, etc.
  • Optional auth secret (only when upstream requires credentials)
  • Supports discovery with cache policy (TTL + stale-if-error)
  • Per-subject tool policy filtering
  • Circuit breaker for upstream reliability

​
Rate Limiting

Gateway enforces per-connection and per-namespace rate limits:
​
GATEWAY_CLAIM_REGISTRATION_RATE_LIMIT_PER_MINUTE
integer
default:"30"
Claim registration attempts per connection + namespace (set 0 to disable)
​
GATEWAY_MCP_TOOL_CALL_RATE_LIMIT_PER_MINUTE
integer
default:"120"
MCP tool call bursts per connection + namespace (set 0 to disable)

​
Timeouts

Gateway applies route-class timeouts:
Route ClassDefault TimeoutEnvironment Variable
Admin20sGATEWAY_ADMIN_TIMEOUT_SECONDS
Proxy120sGATEWAY_PROXY_TIMEOUT_SECONDS
MCP Runtime90sGATEWAY_MCP_TIMEOUT_SECONDS

​
Metrics

Gateway exposes Prometheus-style metrics at GET /metrics: 
sigilum_gateway_auth_reject_total{reason="..."}
sigilum_gateway_replay_detected_total
sigilum_gateway_upstream_requests_total{protocol="...",outcome="..."}
sigilum_gateway_upstream_latency_seconds_{count,sum}{protocol="...",outcome="..."}
sigilum_gateway_upstream_error_total{class="..."}
sigilum_gateway_mcp_discovery_total{result="..."}
sigilum_gateway_mcp_tool_call_total{result="..."}
sigilum_gateway_requests_in_flight
sigilum_gateway_shutdown_drain_total{outcome="..."}
sigilum_gateway_shutdown_drain_seconds_{count,sum}{outcome="..."}
The /metrics endpoint requires admin access policy enforcement. Configure GATEWAY_ADMIN_ACCESS_MODE appropriately.

​
Next Steps

Proxy Endpoints

Learn about HTTP proxy request flow and signature verification

MCP Runtime

Explore MCP tool discovery, filtering, and execution

Admin Endpoints

Manage connections, credentials, and service catalog

Build docs developers (and LLMs) love

Get started for freeTalk to us