# GCP API Gateway

- Canonical URL: https://docs.fairvisor.com/docs/gateway/gcp-api-gateway/
- Section: docs
- Last updated: n/a
> Integrating Fairvisor Edge with Google Cloud API Gateway/ESPv2 external auth pattern.


For GCP managed gateway stacks, use an external authorization pattern that calls Fairvisor before backend proxying.

## Architecture

```text
Client -> API Gateway / ESPv2 -> auth check -> Fairvisor /v1/decision
                                         | allow -> backend
                                         | reject -> 429
```

## Required decision headers

Forward these to Fairvisor on each decision request:

- `X-Original-Method`
- `X-Original-URI` (full path + query)
- `Authorization` (if JWT claims are used)
- `X-Forwarded-For` (original client IP)

## External auth service contract

Your auth hook (service, middleware, or sidecar) should:

1. Build Fairvisor decision request from incoming gateway request
2. Call `POST /v1/decision`
3. If `200`, continue to backend
4. If `429`, stop pipeline and return reject with Fairvisor headers

## Practical config guidance

- Keep Fairvisor call timeout in 200-500 ms range
- Do not perform repeated retries in auth path
- Treat decision timeout/unreachable as explicit fail-open or fail-closed policy per route

Reference policy split: [Gateway Failure Policy](/docs/reference/gateway-failure-policy/).

## Observability

Capture and monitor:

- decision call latency
- decision status distribution (`200`/`429`/`503`)
- fallback events (fail-open or fail-closed path)
- reject reason breakdown from `X-Fairvisor-Reason`

## Security hardening

- Keep Fairvisor endpoint private to GCP network boundary
- Validate that only trusted gateway/auth components can call decision endpoint
- Never trust user-provided `X-Original-*` headers directly from internet clients

## Validation checklist

1. Send known-allowed request and verify backend pass-through
2. Send known-rejected request and verify `429` + `Retry-After`
3. Confirm `X-Fairvisor-Reason` is logged and propagated as intended
4. Simulate Fairvisor outage and validate chosen failure policy

See [Decision API](/docs/reference/api/) for endpoint details.