Proxy Through Gateway
Gateway is served on port 8081. It is not a CRUD API; it is a protected reverse proxy for configured resources.
Operator Endpoints
Section titled “Operator Endpoints”| Method | Path | Purpose |
|---|---|---|
GET | /health | Liveness check. |
GET | /ready | Readiness check. |
GET | /metrics | Prometheus metrics. |
GET | /metrics.json | JSON metrics. |
POST | /internal/revocations/reload | Reload revocation snapshot. |
Request Requirements
Section titled “Request Requirements”| Input | Required | Purpose |
|---|---|---|
Authorization: Bearer ... | yes | Inbound Caracal mandate. |
X-Caracal-Resource | yes | Resource identifier used to find a Gateway binding. |
| Request path | yes | Forwarded to the configured upstream after traversal checks. |
Gateway ignores client attempts to set X-Caracal-Client-ID; the client ID is bound by Gateway configuration.
Denial Checks
Section titled “Denial Checks”Gateway rejects before upstream dispatch. Treat these checks as the safety gate in front of every protected upstream.
| Stage | Checks |
|---|---|
| Request preflight | Bearer token exists, token size is bounded, X-Caracal-Resource exists, and request path is not traversal. |
| Token validation | Token is well formed, not expiring inside the preflight window, signature-valid, not replayed, not revoked, and includes a zone. |
| Binding resolution | (zone_id, resource) has a Gateway binding and the bound upstream passes host safety checks. |
| STS exchange | Gateway’s STS circuit is closed and the signed exchange succeeds. |
Forwarding Behavior
Section titled “Forwarding Behavior”After checks pass, Gateway performs a signed STS exchange, receives a resource mandate, forwards the request to the bound upstream, and emits audit evidence. Request and upstream timeouts are controlled by Gateway service config.
Next Step
Section titled “Next Step”Continue to Use Event Topics to understand the Redis Stream topics that carry audit, invalidation, revocation, and agent lifecycle events.