Organization Scoping

RORCex uses two request headers and one query parameter to control which organizations and stores a request acts on. Understanding these is essential before calling any endpoint.

X-Organization-Context

The X-Organization-Context header tells the API which organization this request acts on behalf of. It is required on all endpoints that are organization-aware (which is most of them).

X-Organization-Context: org_00000k1L2m3N4o5

The value must be the hashkey of your organization or one of its descendant store orgs. It cannot be an org outside your accessible subtree — the API refuses those requests with 403 Forbidden.

Typical usage is to pass your top-level (HQ) org ID so that context-sensitive reads and writes land against your organization record. When you want to act directly on a specific store's org (for example, when issuing a fan-out targeting a single known store), pass that store's org ID instead.

X-Organization-Scope

The X-Organization-Scope header controls how far a request fans out across your org hierarchy. Two values are supported:

Value	Behavior
CURRENT	Default. The request acts on the single org specified in X-Organization-Context only.
CASCADE	The request fans out across the org specified in X-Organization-Context and all of its descendant store orgs.

X-Organization-Scope: CASCADE

CASCADE is honored by HQ analytics endpoints, fan-out operations, and report execution. It is not meaningful (and is ignored) on single-store live-data endpoints — those always operate on a single store identified by store_org_id.

Example: aggregated dashboard across all stores

curl "https://api.rorcex.retailsuccessplatform.com/api/v1/hq/dashboard?date=2026-06-11" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${HQ_ORG_ID}" \
  -H "X-Organization-Scope: CASCADE"

Omitting X-Organization-Scope (or passing CURRENT) on this endpoint returns metrics for the HQ org alone, which typically has no direct lane data — you almost always want CASCADE for analytics calls.

store_org_id — Targeting a Single Store

Endpoints that proxy live lane data (Sales, Inventory, Products, Control, Promotions) require you to identify the specific store you want to read from. Pass its org ID as the store_org_id query parameter:

curl "https://api.rorcex.retailsuccessplatform.com/api/v1/sales/transactions?store_org_id=org_00000f6G7h8I9j0" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${HQ_ORG_ID}"

The store_org_id must be a store org within your accessible set (i.e., a descendant of the org your client is bound to). Passing an unknown or out-of-subtree store org returns 403 Forbidden.

Use the Installs endpoint to enumerate the store_org_id values available to your account.

Isolation and 403 Enforcement

The API strictly enforces your org subtree boundary on every request. There is no way to read or write data belonging to a different operator's organization.

Attempting to act on an out-of-subtree org — whether via X-Organization-Context, store_org_id, or any resource ID that belongs to another org — returns a 403 Forbidden response:

{
  "error": "Forbidden.",
  "message": "The requested organization is not within your accessible scope."
}

This applies equally to:

• Passing another org's ID in X-Organization-Context
• Passing a store that belongs to a different operator in store_org_id
• Referencing resource IDs (e.g., a hostcom_file_id) that were created by a different org

---

Changelog

Date	Change
2026-06-11	Initial publication.