commerce HTTP contracts
Supported HTTP operations, source validators, SDK companions and explicit OpenAPI schema limits.
Supported HTTP operations, source validators, SDK companions and explicit OpenAPI schema limits.
These HTTP contracts are an explicit supported subset, not the whole Core API. Prefer the SDK when it exposes the operation. Authentication schemes are alternatives, not interchangeable tokens. Use the documented consumer context or CLI exchange; never send a raw maker credential as a consumer token. Read the owning guides for permissions, confirmation and asynchronous completion.
GET /portal/businesses/{businessId}/me/bill-preview
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.getBillPreview(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.getBillPreview(...)",
"signature": "getBillPreview(opts?: {\n signal?: AbortSignal;\n }): Promise<BillPreview>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
}
}
OpenAPI metadata (incomplete):
{
"operationId": "getPortalConsumerBillPreview",
"summary": "Return the signed-in consumer's current-window bill preview, computed through the same rating engine and ledger state as invoicing",
"description": "Requires `invoice:read` — the preview carries the plan fee and every rating window, so it is gated exactly like the invoice surface it previews. A caller with no subscription receives the constant empty preview (200), never a 403, so the status code does not disclose whether the organization has a subscription.",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Bill preview. `disclosure: \"transparent\"` → `{ currency, disclosure, recurringFeeCents, windows: [{ windowId, windowStart, windowEnd, chargeCount, ratedNanos }], totals: { ratedNanos, fundedNanos, receivableNanos }, allowances: [{ kind, state, remainingNanos, heldNanos, consumedNanos, expiresAt }], usageRating: { pendingEventCount, unratableEventCount, oldestUnratedServedAt } }`. `totals` sums POSTED charges only, so `usageRating` states the served usage those totals CANNOT include — usage still awaiting rating (`pendingEventCount`, drains on its own) that reached a TERMINAL quarantine and will never be priced (`unratableEventCount`; bookkeeping-only quarantine families such as a retry repair are excluded, so this is the same number the builder-plane `usage summary` reports for the same traffic). All-zero counts mean the totals are the whole bill; a client must not present a `$0` total as final while either count is non-zero. `disclosure: \"opaque\"` (authored opaque, or the served release's policy cannot be resolved — disclosure fails closed) → `{ currency, disclosure, recurringFeeCents, allowances: [{ kind, state, expiresAt, display }] }` where `display` is the plan-authored `{ kind: \"multiplier\", allowanceUnits, remainingUnits, consumedUnits }` or `{ kind: \"fraction\", consumedBasisPoints, remainingBasisPoints }` — never windows, totals, or nanodollar amounts.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
PATCH /portal/businesses/{businessId}/me/spend-cap
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.setSpendCap(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.setSpendCap(...)",
"signature": "setSpendCap(input: {\n maxMonthlySpendCents: number | null;\n }): Promise<SpendCapResult>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
},
"requestValidator": {
"name": "updateSpendCapSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L97",
"declaration": "export const updateSpendCapSchema = z.object({\n maxMonthlySpendCents: z\n .number()\n .int()\n .min(1, \"maxMonthlySpendCents must be a positive integer\")\n .nullable(),\n organizationId: z.string().uuid().optional(),\n});"
}
}
OpenAPI metadata (incomplete):
{
"operationId": "updatePortalConsumerSpendCap",
"summary": "Set or remove the monthly spend cap for the signed-in consumer on a product portal",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Spend cap updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
GET /portal/businesses/{businessId}/me/plan-offers
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.plans.getPlanOffers(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.plans.getPlanOffers(...)",
"signature": "getPlanOffers(): Promise<PlanOffer__5ab47cb32b7d[]>;",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L61",
"declarationName": "PlansResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "OnboardingResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1104"
},
{
"name": "Plan",
"source": "packages/farthershore-js/dist/types.d.ts#L127"
},
{
"name": "PlanOffer__5ab47cb32b7d",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L31"
},
{
"name": "StartOnboardingInput",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L27"
},
{
"name": "SubscribeInput",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L5"
},
{
"name": "SubscribeResult",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L44"
}
]
}
}
OpenAPI metadata (incomplete):
{
"operationId": "listPortalConsumerPlanOffers",
"summary": "List the purchasable plan offers (plan + offerFingerprint) for the signed-in consumer, including the current pinned plan version",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Plan offers — `[{ compiledPlanId, plan, offerFingerprint }]`. `offerFingerprint` is the billing fingerprint of that CompiledPlan version; echo it back as `offerFingerprint` on checkout/onboarding to get a 409 PLAN_OFFER_CHANGED if the plan's economics changed since render.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/checkout-session
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.plans.subscribe(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.plans.subscribe(...)",
"signature": "subscribe(input: SubscribeInput): Promise<SubscribeResult>;",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L61",
"declarationName": "PlansResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "OnboardingResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1104"
},
{
"name": "Plan",
"source": "packages/farthershore-js/dist/types.d.ts#L127"
},
{
"name": "PlanOffer__5ab47cb32b7d",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L31"
},
{
"name": "StartOnboardingInput",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L27"
},
{
"name": "SubscribeInput",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L5"
},
{
"name": "SubscribeResult",
"source": "packages/farthershore-js/dist/resources/plans.d.ts#L44"
}
]
},
"requestValidator": {
"name": "checkoutSessionSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L35",
"declaration": "export const checkoutSessionSchema = z\n .object({\n compiledPlanId: z.string().min(1, \"compiledPlanId is required\"),\n organizationId: z.string().uuid().optional(),\n successUrl: z.string().url().optional(),\n cancelUrl: z.string().url().optional(),\n // E2 (Managed Stripe Price Integrity) — OPTIONAL price-consent echo: the\n // `offerFingerprint` from GET /me/plan-offers. When present and stale\n // (target plan's economics changed) the route 409s PLAN_OFFER_CHANGED\n // before any provider session is created. Absent -> legacy behavior.\n offerFingerprint: z.string().min(1).optional(),\n })\n .strict();"
}
}
OpenAPI metadata (incomplete):
{
"operationId": "createPortalCheckoutSession",
"summary": "Create a Stripe Checkout session for the signed-in consumer",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"responses": {
"200": {
"description": "Checkout session created. Repeated calls with the same plan return the same `checkoutAttemptId` and provider URL.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"url",
"checkoutAttemptId"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Stripe Checkout session URL"
},
"checkoutAttemptId": {
"type": "string",
"description": "Stable id of the CheckoutAttempt row"
}
}
},
{
"type": "object",
"required": [
"subscriber",
"subscription",
"checkoutAttemptId"
],
"properties": {
"subscriber": {
"type": "object",
"required": [
"id",
"businessId",
"status"
],
"properties": {
"id": {
"type": "string"
},
"businessId": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"subscription": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"compiledPlanId": {
"type": "string"
},
"lifecycle": {
"type": "string"
}
}
},
"checkoutAttemptId": {
"type": "string"
},
"autoApiKey": {
"type": "object"
},
"autoApiKeyError": {
"type": "string"
}
}
}
],
"description": "Discriminated by `url` (paid) vs `subscriber` (free plan). Both shapes carry `checkoutAttemptId`."
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"503": {
"description": "Billing provider unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/billing-portal-session
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.openBillingPortal(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.openBillingPortal(...)",
"signature": "openBillingPortal(input?: {\n returnUrl?: string;\n }): Promise<{\n url: string;\n }>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
},
"requestValidator": {
"name": "billingPortalSessionSchema",
"source": "apps/core/src/validation/portal-subscription-schemas.ts#L4",
"declaration": "export const billingPortalSessionSchema = z.object({\n returnUrl: z.string().url().optional(),\n});"
}
}
OpenAPI metadata (incomplete):
{
"operationId": "createPortalBillingPortalSession",
"summary": "Create a Stripe billing portal session for subscription management",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"responses": {
"200": {
"description": "Billing portal session created",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/balance-top-up
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"requestValidator": {
"name": "prepaidTopUpSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L108",
"declaration": "export const prepaidTopUpSchema = z\n .object({\n amountCents: z.number().int().min(100).max(100_000),\n requestId: z.string().uuid(),\n successUrl: z.string().url().optional(),\n cancelUrl: z.string().url().optional(),\n })\n .strict();"
},
"responseEvidence": {
"name": "CreatePrepaidTopUpResult",
"source": "apps/core/src/services/stripe/prepaid-top-up-checkout.ts#L17",
"declaration": "export type CreatePrepaidTopUpResult =\n | Readonly<{ ok: true; checkoutUrl: string }>\n | Readonly<{\n ok: false;\n reason:\n | \"amount_out_of_range\"\n | \"subscription_or_billing_missing\"\n | \"top_up_not_enabled\"\n | \"policy_unresolvable\"\n | \"stripe_error\";\n message?: string;\n }>;"
},
"note": "No typed resource method. A signed-in subscriber calls POST /portal/businesses/:businessId/me/balance-top-up through the public Frontend SDK fs.core() escape hatch, which supplies authentication and portal scope. POST the validator's exact JSON fields. Success is the ok:true branch with checkoutUrl; the other result branches become HTTP errors in apps/core/src/services/portal-customer/create-prepaid-top-up.ts."
}
OpenAPI metadata (incomplete):
{
"operationId": "createPortalConsumerBalanceTopUp",
"summary": "Create a Stripe Checkout session that adds funds to the signed-in consumer's usage balance",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"responses": {
"200": {
"description": "Balance checkout created",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"502": {
"description": "Billing provider rejected checkout creation",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
GET /portal/businesses/{businessId}/me/subscription
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.subscription(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.subscription(...)",
"signature": "subscription(opts?: {\n signal?: AbortSignal;\n }): Promise<Subscription | null>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
}
}
OpenAPI metadata (incomplete):
{
"operationId": "getPortalConsumerSubscription",
"summary": "Get subscription details for the signed-in consumer",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Subscription details",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/cancel
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.cancelSubscription(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.cancelSubscription(...)",
"signature": "cancelSubscription(input?: {\n reason?: string;\n }): Promise<CancelSubscriptionResult>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
},
"requestValidator": {
"name": "cancelSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L58",
"declaration": "export const cancelSchema = z\n .object({\n organizationId: z.string().uuid().optional(),\n reason: z.string().optional(),\n returnUrl: z.string().url().optional(),\n })\n // .strict() to match the sibling portal schemas (onboarding /\n // checkoutSession / restore / changePlan). Unknown keys are rejected\n // so a future mass-assignment regression can't sneak in.\n .strict();"
}
}
OpenAPI metadata (incomplete):
{
"operationId": "cancelPortalConsumerSubscription",
"summary": "Cancel the signed-in consumer's subscription",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Cancellation result",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/restore
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.restoreSubscription(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.restoreSubscription(...)",
"signature": "restoreSubscription(): Promise<RestoreSubscriptionResult>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
},
"requestValidator": {
"name": "restoreSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L76",
"declaration": "export const restoreSchema = z\n .object({\n compiledPlanId: z.string().min(1).optional(),\n organizationId: z.string().uuid().optional(),\n returnUrl: z.string().url().optional(),\n })\n .strict();"
},
"note": "SDK limitation: restoreSubscription takes no arguments and returns raw:unknown. Core's free-plan restore branch requires compiledPlanId; use the documented HTTP body when that branch applies. The exact successful wire response remains unspecified by OpenAPI."
}
OpenAPI metadata (incomplete):
{
"operationId": "restorePortalConsumerSubscription",
"summary": "Restore a fully cancelled subscription by resubscribing to a plan",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"responses": {
"200": {
"description": "Restore result",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
POST /portal/businesses/{businessId}/me/change-plan
OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.
SDK companion: client.billing.changePlan(...). Resolve its named inputs and outputs in the SDK declaration reference.
{
"limitation": "OpenAPI uses GenericObject or GenericObjectArray here and does not fully specify the HTTP contract. These are documentation placeholders, not permission to send arbitrary fields. SDK signatures describe normalized SDK inputs and outputs, not exact wire response envelopes. Source validators specify structural inputs; route authorization and semantic checks still apply.",
"sdk": {
"usage": "client.billing.changePlan(...)",
"signature": "changePlan(input: {\n compiledPlanId: string;\n }): Promise<ChangePlanResult>;",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L13",
"declarationName": "BillingResource",
"page": "generated/frontend-sdk/root",
"typeReferences": [
{
"name": "BillPreview",
"source": "packages/farthershore-js/dist/types.d.ts#L1284"
},
{
"name": "CancelSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1122"
},
{
"name": "ChangePlanResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1144"
},
{
"name": "RestoreSubscriptionResult",
"source": "packages/farthershore-js/dist/types.d.ts#L1134"
},
{
"name": "SpendCapResult",
"source": "packages/farthershore-js/dist/resources/billing.d.ts#L5"
},
{
"name": "Subscription",
"source": "packages/farthershore-js/dist/types.d.ts#L739"
}
]
},
"requestValidator": {
"name": "changePlanSchema",
"source": "apps/core/src/validation/portal-schemas.ts#L87",
"declaration": "export const changePlanSchema = z\n .object({\n compiledPlanId: z.string().min(1, \"compiledPlanId is required\"),\n organizationId: z.string().uuid().optional(),\n })\n .strict();"
},
"note": "SDK/Core mismatch: the SDK advertises successUrl and cancelUrl, but Core's strict validator does not accept those keys. Omit them. The validator below is authoritative for HTTP input; SDK result types describe normalized output, not the exact wire envelope."
}
OpenAPI metadata (incomplete):
{
"operationId": "changePortalConsumerPlan",
"summary": "Upgrade or downgrade the signed-in consumer's plan",
"tags": [
"portal-customer"
],
"security": [
{
"consumerBearerAuth": []
},
{
"siteShellServiceJwt": [],
"personaSessionCookie": []
}
],
"parameters": [
{
"name": "businessId",
"in": "path",
"required": true,
"description": "Business identifier",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"responses": {
"200": {
"description": "Plan change result",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
}
}
}
{
"browserBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Browser session token forwarded by the frontend"
},
"consumerBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Consumer portal session token forwarded by the frontend"
},
"cliUserSessionBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "cli_access JWT",
"description": "Short-lived CLI access JWT exchanged from a live user-bound fscli_ session. Eligibility is revalidated from current organization membership and role grants."
},
"makerTokenAccessBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "cli_access JWT",
"description": "Short-lived CLI access JWT exchanged from an organization-scoped mk_ MakerToken. Authority is limited to the token's frozen exact grants and business scope."
},
"rawCliCredentialBearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "fscli_ session or mk_ MakerToken",
"description": "Raw CLI credential accepted only by exchange, organization discovery, and CLI-session revocation infrastructure."
},
"serviceJwtBearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Ed25519 service JWT",
"description": "Short-lived Farther Shore service identity JWT for internal machine calls"
},
"siteShellServiceJwt": {
"type": "apiKey",
"in": "header",
"name": "x-fs-service-jwt",
"description": "Short-lived Farther Shore site-shell service JWT with proxy:trust scope"
},
"localPreviewProxyLease": {
"type": "apiKey",
"in": "header",
"name": "x-fs-local-persona-proxy",
"description": "CLI-process-only local-preview lease (fslpl_…) attached by the `farthershore frontend dev|preview --live` loopback proxy together with `x-fs-local-preview-origin` (the exact http://localhost:<port> origin it was issued for). Verified against Core's lease store and pinned to one persona/environment/business/portal host; a raw header pair without a live lease grants nothing. Never sent by browser code."
},
"personaSessionCookie": {
"type": "apiKey",
"in": "cookie",
"name": "__Host-fs_persona_session",
"description": "Host-only HttpOnly persona session cookie. Accepted only through a trusted boundary: together with the hosted site shell's service JWT, or through the CLI's localhost preview proxy presenting a verified local-preview lease (x-fs-local-persona-proxy + x-fs-local-preview-origin). Never as a bearer."
}
}