---
title: "Protect Upstreams"
url: "https://docs.caracal.run/services/gateway/"
markdown_url: "https://docs.caracal.run/markdown/services/gateway.md"
description: "Service reference for protected reverse proxying, STS exchange, revocation checks, and upstream safety."
page_type: "reference"
concepts: []
requires: []
---

# Protect Upstreams

Canonical URL: https://docs.caracal.run/services/gateway/
Markdown URL: https://docs.caracal.run/markdown/services/gateway.md
Description: Service reference for protected reverse proxying, STS exchange, revocation checks, and upstream safety.
Page type: reference
Concepts: none
Requires: none

---

Gateway is the protected-resource ingress. It validates inbound Caracal authority, checks replay and revocation, exchanges with STS, and forwards to configured upstreams only after safety checks pass.

## Runtime

| Property | Value |
| --- | --- |
| Port | `8081` |
| Health/readiness | `/health`, `/ready` |
| Metrics | `/metrics`, `/metrics.json` |
| Revocation reload | `POST /internal/revocations/reload` |

## Request Path

```mermaid
sequenceDiagram
  participant Client
  participant Gateway
  participant STS
  participant Upstream
  participant Audit
  Client->>Gateway: bearer token + X-Caracal-Resource
  Gateway->>Gateway: verify JWT, jti, revocation, binding, path, upstream safety
  Gateway->>STS: signed per-request exchange
  STS-->>Gateway: resource mandate
  Gateway->>Upstream: proxied request
  Gateway->>Audit: audit event or replay file
```

## Deny-Before-Upstream Checks

- Missing, malformed, oversized, expiring, replayed, revoked, or signature-invalid bearer token.
- Missing `X-Caracal-Resource`.
- No binding for `(zone_id, resource)`.
- Client-supplied `X-Caracal-Client-ID`.
- Path traversal.
- Operation (method and path) not declared on an enforced resource, or missing the operation's required scope.
- STS exchange failure or open STS circuit.
- Unsafe upstream destination.

## Configuration Highlights

| Variable | Purpose |
| --- | --- |
| `STS_URL` | STS endpoint for exchange and JWKS. |
| `GATEWAY_STS_HMAC_KEY` | Signs Gateway exchange requests. |
| `MAX_REQUEST_BYTES` | Request body limit, default 10 MiB. |
| `UPSTREAM_HOST_ALLOWLIST` | Optional egress allowlist pinning upstreams to named hosts. |
| `JTI_FAIL_OPEN` | Forbidden in published modes. |
| `AUDIT_REPLAY_DIR` | Replay directory for audit events. |

## Next Step

Use [Ingest Audit Evidence](/services/audit/) to understand how Gateway, STS, API, Coordinator, and Control evidence becomes searchable audit state.

## Related Pages

- [Proxy Through Gateway](/api/gateway/)
- [Enforce Boundaries](/architecture/trust-boundaries/)
- [Harden Production](/operations/tls-hardening/)