FAIRVISOR Docs
⌘K
GitHub fairvisor.com

GCP API Gateway

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

Architecture

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.

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 for endpoint details.

MD