X‑UPSTREAM‑ENV for HCP Gateway

Quick Reference

• Header-based environment routing for HCP (Health Care Platform) APIs
• X‑Upstream‑Env is a required, validated custom header used by the HCP Gateway to route a single public endpoint to multiple internal environments (e.g., dev, stage, test).
• Clients must send a permitted value (typically dev, stage, or test) or requests may default or fail with 404 NOT_FOUND. Ensure every proxy in front of HCP preserves this header.
• Scope
  • Applies to: Any service calling HCP‑exposed endpoints.
  • Does not cover: Non‑HCP gateways with different routing semantics.

---

X-UPSTREAM-ENV is a custom HTTP header commonly used in API ecosystems to indicate the target environment for an upstream service call. It helps route requests to the correct backend environment without changing the base URL.

Why use it?

• Environment Routing: Avoids hardcoding multiple URLs for different environments.
• Consistency: Same API endpoint can serve multiple environments based on header.
• Flexibility: Useful in microservices and API gateway setups where routing logic depends on headers.

Contract

Header name & casing

• Canonical name: X-Upstream-Env
• HTTP is case-insensitive, but normalize to this exact form for consistency in docs, logs, and matchers.

Expected values (allow‑list)

• dev – Development environment
• stage – Staging / Integration environment
• perf – Performance testing environment
• test – General testing environment
• reg – Regression testing environment

Requirement level

• Required for most non‑prod calls (HCP interprets it to select the upstream partition).
• In prod, the header is omitted (defaults apply)

Interaction with Hostnames

• Hostnames like api-stg.uhg.com (non‑prod) are not sufficient to determine the final target; the header selects the upstream environment behind the gateway (e.g., route stg host + dev header to DEV backends).

---

Client Usage

cURL

# Payment Methods search (non-prod)
curl --location --request POST \
  'https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v1/payment-methods/search' \
  --header 'X-Upstream-Env: dev' \
  --header 'X-Merchant-Id: <merchant-id>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": { "name": "Testing", "email": "Jo@test.com" }
  }'

info

This pattern (host points to stg, header points to dev) is used across Checkout and Session flows.

---

Server‑side Behavior (HCP Gateway)

1. Header inspection: HCP reads X‑Upstream‑Env early in request processing.
2. Routing decision: The value selects the upstream cluster/partition (DEV, STAGE, PROD).
3. Policy enforcement: If invalid/unsupported, HCP will reject with 404 NOT_FOUND.
4. Auth is separate: JWT/OAuth validation is orthogonal; a valid token + invalid env will still fail.

---

Validation, Defaults & Error Handling

Situation	Expected Behavior	Example Evidence
Missing header (non‑prod)	404 NOT_FOUND	Session API discussions/updates reference NOT_FOUND when preconditions fail; treat missing/invalid env similarly per API policy.
Invalid value	404 NOT_FOUND	Teams align on strict validation to avoid wrong‑env effects.
Auth OK, env wrong	403 FORBIDDEN	Multiple cURLs show correct tokens still failing for logical reasons (env/merchant/config mismatch).

Error Response Examples

• 403 FORBIDDEN

  {
    "title": "FORBIDDEN",
    "status": 403,
    "detail": "403 FORBIDDEN",
    "errorDetails": null
  }

• 404 NOT_FOUND

  {
    "message": "no Route matched with those values",
    "request_id": "3552964e1362fb657362ba50b3a9af27"
  }

  note

  Typical HCP Gateway error response for missing or invalid X-Upstream-Env values. The message and request_id fields may vary by request.

• The header is required for most non-prod calls. If omitted or invalid, the API may default or return a 404 NOT_FOUND error.
• If the header value is valid but does not match the authenticated user's environment or merchant configuration, a 403 FORBIDDEN is returned.
• Authentication and environment validation are independent: a valid token with an invalid or mismatched environment will still result in an error.

---

Security Notes

• Header ≠ authorization. Route selection is not a permission boundary; always require valid OAuth/JWT scopes.
• Least privilege: Tokens scoped to the chosen environment.
• Audit & logging: Log the header value alongside request IDs to diagnose cross‑env issues.

---

FAQ

Q: Can I omit X‑Upstream‑Env in non‑prod?
A: Not recommended. Many flows expect it; omission can misroute or fail with 400.

Q: Why do I see 403 from Azure Application Gateway when my header is present?
A: That’s a network/perimeter block, not the HCP gateway decision. Validate AGW rules, IP allowlists, and path configs first; then re‑test with the same header.

Q: Should I hardcode dev or stage at ingress?
A: No. Preserve the client’s explicit intent. Hardcoding undermines cross‑env testing patterns observed in your teams.

---