Protect a Gateway-Routed HTTP API
Use Gateway-routed protection when the upstream is HTTP-routable and you want Caracal to enforce every request before it reaches the target. The agent receives a short-lived Caracal mandate; Gateway verifies it, resolves the resource route, attaches the configured upstream credential when needed, forwards the request, and writes action-result audit.
Prerequisites
Section titled “Prerequisites”- Gateway, STS, Redis revocation state, audit ingestion, and the upstream ready.
- A resource with stable identifier, Gateway application, provider, scopes, and declared operations.
- An active policy granting only the calling role and an application SDK configured for the same resource.
When to Use Gateway
Section titled “When to Use Gateway”| Use Gateway when | Use another guide when |
|---|---|
| The upstream is HTTP, REST, MCP-over-HTTP, or another Gateway-routable target. | The service must verify mandates inside its own process. |
| You want provider credentials to stay inside the trusted Gateway/STS boundary. | The application must call the provider directly and only needs attribution. |
| You want action-result audit from the central Gateway. | The resource server owns result audit after adapter verification. |
| Responses are request/response or streamed HTTP, such as SSE. | The upstream requires WebSocket connections, which Gateway does not proxy. |
For in-process enforcement, use Protect an Express App, Protect a FastMCP App, Protect a Go net/http Service, or Protect an MCP Server.
Create or Select the Resource
Section titled “Create or Select the Resource”Open the web console for your deployment (http://localhost:3001 on the packaged local stack).
Create or select a resource with:
| Field | Guidance |
|---|---|
| Resource identifier | Stable audience URI, such as resource://pipernet. |
| Scopes | Action-oriented scopes, such as pipernet:read and pipernet:submit. |
| Upstream URL | Network URL the Gateway can reach. |
| Gateway application | The Caracal application identity Gateway uses for upstream exchanges. |
| Upstream credential provider | The provider record Gateway uses to attach no credential, a Caracal mandate, OAuth token, API key, or bearer token. |
Keep the resource identifier stable even when upstream hosts or provider bindings change.
Choose Provider Auth Mode
Section titled “Choose Provider Auth Mode”| Provider type | Use when |
|---|---|
| None | Gateway enforces Caracal access and the upstream expects no credential. |
| Caracal mandate | The upstream verifies Caracal mandates directly. |
| OAuth client credentials | Gateway needs a machine OAuth token. |
| OAuth authorization code | Gateway needs a connected upstream account (delegated OAuth consent). |
| API key | Gateway attaches a sealed static API key in a configured header. |
| Bearer token | Gateway attaches a sealed pre-issued bearer token. |
Use Define Resources and Providers for field definitions and Provider Recipes for concrete OpenAI, Google, GitHub, Slack, and internal API examples.
Route Calls Through Gateway
Section titled “Route Calls Through Gateway”Gateway-routed requests include:
| Request part | Value |
|---|---|
| URL | Gateway URL from your runtime profile (gateway_url; http://localhost:8081 on the local stack). |
Authorization | Bearer <Caracal mandate>. |
X-Caracal-Resource | Resource identifier. |
| Path | The protected path you configured for the upstream. |
SDKs can build the Gateway request and inject headers for you:
- TypeScript:
caracal.gatewayRequest()pluscaracal.transport({ scopes }) - Python:
caracal.gateway_request()pluscaracal.transport(scopes=[...]) - Go:
GatewayRequest()plusTransport(nil, CallOptions{Scopes: ...})
The request helper supplies only the Gateway URL and X-Caracal-Resource; the scoped transport mints and attaches the required use=gateway mandate. Do not combine the helper with raw lifecycle headers.
Verify Authorization and Audit
Section titled “Verify Authorization and Audit”Run these checks before treating the route as ready:
| Check | Expected result |
|---|---|
| Allowed request | Gateway forwards to upstream and records action-result audit. |
| Missing mandate | Gateway rejects the request. |
| Missing scope | STS or Gateway rejects the request. |
| Wrong resource header | Gateway rejects or routes to a different configured resource. |
| Revoked session | Gateway rejects the old mandate. |
Open the web console Audit and filter by the request ID. A complete Gateway-routed call has both authorization evidence from STS and action-result evidence from Gateway.
Gateway preserves the HTTP method, path, query, body, and streaming response. It replaces caller authorization with the selected provider credential, strips upgrade behavior, does not proxy WebSockets, and does not retry an upstream mutation. A stale revocation snapshot fails closed with 503 before forwarding.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Gateway returns 403 | Token expiry, resource ID, scopes, revocation, and X-Caracal-Resource. |
| Upstream is unreachable | Upstream URL must be reachable from the Gateway container or deployment. |
| Provider credential not attached | Resource must bind exactly one upstream credential provider. |
| Authorization audit exists but action-result audit is missing | The request did not reach Gateway or failed before route execution. |
Next Step
Section titled “Next Step”Run Check Provider Readiness, then use Debug Authorization Decisions for any deny.