Farther ShoreDocs
Go to Farther Shore
Getting startedCore conceptsLaunch checklist
ProductsUpstream routingEnvironmentsDeveloper portals
Billing strategiesPlans and limitsSubscribersAPI keys
Gateway enforcementUsage meteringLimits and creditsGateway sharding
Launch a request-counted product15mAdd monthly included usageAdd subscription plus overageCreate a prepaid credits productMeter AI token usageAdd a custom meterIssue and test an API keyDebug a denied requestUpdate product docsPrepare for launch
TroubleshootingGateway response codesMeter namingPlatform docs publishing
Status
Docs/Build Products/Upstream routing

Upstream routing

Connect Farther Shore to the API you already run.

PreviousProductsNextEnvironments

On this page

What the gateway forwardsUpstream URLUpstream authenticationHeadersTesting upstream routing

The gateway forwards allowed subscriber requests to your upstream API. Upstream routing is the connection between the public product hostname and the service that actually handles the work.

What the gateway forwards

For an allowed request, the gateway forwards:

  • HTTP method
  • path and query string
  • request body
  • selected request headers
  • gateway-added context headers when configured

The gateway also applies enforcement before forwarding. Denied requests do not reach the upstream.

Upstream URL

Use the stable base URL for the API environment you want the product to call.

https://api.example.com

If your upstream has versioned paths, keep the base URL stable and let callers send the path:

GET https://<product-host>/v1/weather?city=Boston

The gateway forwards the request to:

GET https://api.example.com/v1/weather?city=Boston

Upstream authentication

If your upstream requires its own secret, configure that secret in Farther Shore instead of asking subscribers to send it. Subscribers should use their Farther Shore API key. The gateway can then authenticate to the upstream on their behalf.

This keeps upstream credentials private and lets you rotate subscriber API keys independently from upstream secrets.

Headers

Design upstream behavior so it does not depend on subscribers sending internal headers. Subscriber-facing headers should be documented in product docs. Internal headers should be configured at the gateway or upstream integration layer.

Testing upstream routing

After publishing a product:

curl https://<product-host>/health \
  -H "Authorization: Bearer <subscriber-api-key>"

Check three things:

  1. The gateway allows the request.
  2. The upstream receives the expected path and method.
  3. Usage is emitted for the request.

If the upstream receives no traffic, start with Gateway response codes and Troubleshooting.