---
title: "Proxy Through Gateway"
url: "https://docs.caracal.run/api/gateway/"
markdown_url: "https://docs.caracal.run/markdown/api/gateway.md"
description: "Protected reverse-proxy behavior, routing headers, denial checks, and upstream forwarding."
page_type: "api"
concepts: []
requires: []
---

# Proxy Through Gateway

Canonical URL: https://docs.caracal.run/api/gateway/
Markdown URL: https://docs.caracal.run/markdown/api/gateway.md
Description: Protected reverse-proxy behavior, routing headers, denial checks, and upstream forwarding.
Page type: api
Concepts: none
Requires: none

---

Gateway is served on port `8081`. It is not a CRUD API; it is a protected reverse proxy for configured resources.

## 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

| 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

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

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

Continue to [Use Event Topics](/api/event-topics/) to understand the Redis Stream topics that carry audit, invalidation, revocation, and agent lifecycle events.

## Related Pages

- [Protect Upstreams](/services/gateway/)
- [Enforce Boundaries](/architecture/trust-boundaries/)
- [Protect an MCP Server](/guides/protect-mcp/)