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/Monetize/API keys

API keys

Issue, rotate, revoke, and test the credentials your subscribers use to call your products.

# Subscriber calling your product
curl https://<product-host>/v1/example \\
  -H "Authorization: Bearer <subscriber-api-key>"
curl -X POST https://api.farthershore.com/v1/keys \\
  -H "Authorization: Bearer <builder-token>" \\
  -d '{
    "subscription_id": "sub_2nF...",
    "name": "production",
    "environment": "live"
  }'
Rotate
curl -X POST https://api.farthershore.com/v1/keys/<id>/rotate \\
  -H "Authorization: Bearer <builder-token>" \\
  -d '{ "grace_seconds": 86400 }'
PreviousSubscribersNextGateway enforcement

API keys are the connective tissue between a subscriber's request and the product, subscription, and plan it bills against. They are the credential subscribers use whenever they call a Farther Shore product.

Most product docs only need to mention subscriber API keys. The other key types are operational and do not show up in customer-facing flows.

Key types

Key typeUsed byPurpose
builderProduct ownersManage products in the builder console.
makerAutomationValidate or sync product configuration from CI.
subscriberSubscribersCall live products through the gateway.

How subscribers use keys

The common pattern is a bearer token. Send the key in the Authorization header on every request.

If your product uses a different header, document the substitution clearly in your product portal so subscribers do not have to dig.

Key issuance flow

  1. 1

    Subscriber chooses a plan

    From your portal or your own checkout. The plan determines which environments and limits the resulting key gets.

  2. 2

    Core creates the subscription

    Farther Shore records the subscription, attaches it to the right plan, and prepares it to issue keys.

  3. 3

    Subscriber creates a key

    They name it, pick its environment, and copy it. The plaintext is shown once; only the prefix is visible afterward.

  4. 4

    Edge picks it up

    Farther Shore publishes the key metadata to the edge cache so the next gateway request can resolve the subscriber quickly.

  5. 5

    Gateway validates every call

    Each request is authenticated against the cache, checked for plan headroom, forwarded when allowed, and metered.

Rotation

Rotate keys when:

  • a key may have been exposed
  • a team member leaves
  • a subscriber wants separate keys per environment
  • a customer wants regular credential hygiene

Rotation should be non-disruptive. Issue a new key, keep the old key valid for a grace window, update the subscriber's client, and revoke the old key after traffic drains to zero.

You can use key labels, request timestamps, and gateway response codes to confirm traffic has moved to the new credential before revoking the old one.

Revocation

Revoking is final. Use it when a key is known-compromised and you need traffic to fail as soon as edge configuration refreshes. For everything else, prefer rotation with a grace window.

If a revoked key still appears to work, verify:

  • the request is using the expected product hostname
  • the key was actually revoked, not only renamed
  • the gateway has received the updated edge configuration
  • the subscriber does not have another active key

Safe handling

Never ask a subscriber to paste a full API key into a ticket or chat. Ask for:

  • the key label
  • last four visible characters if the portal shows them
  • request timestamp
  • response code
  • product hostname

Testing a key

Use the recipe Issue and test an API key to verify the complete subscriber request path.