Authentication

All RORCex endpoints require an OAuth 2.0 Bearer token. Tokens are obtained from the Identity API using the Client Credentials flow. The token's token_type in the JWT payload is service_account.

Obtaining a Token

Request a token from the Identity service with the RORCex permissions your integration needs:

curl -X POST https://identity.retailsuccessplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=installs.view reports.view reports.execute"

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIs..."
}

Store this token securely on your backend. All RORCex API calls must be made server-side — never expose your access token to the browser.

Using the Token

Include the token in the Authorization header of every request, along with the X-Organization-Context header identifying the org your request acts on:

curl https://api.rorcex.retailsuccessplatform.com/api/v1/installs \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Organization-Context: org_00000k1L2m3N4o5"

See Organization Scoping for details on X-Organization-Context and the X-Organization-Scope: CASCADE header used for multi-store operations.

Permissions

Request only the permissions your integration needs. Each permission unlocks a specific surface of the API.

Permission	Unlocks
installs.view	GET /installs — list and inspect RORC lane installs
reports.view	GET /reports — list available report definitions
reports.execute	POST /reports/{id}/run — execute a report; GET /reports/runs/{run_id} — poll run status and retrieve results
hostcom-batches.view	GET /hostcom/dispatches and GET /hostcom/dispatches/{id} — inspect dispatch history
hostcom-batches.create	POST /hostcom/files/author — author and validate a hostcom file
hostcom-batches.dispatch	POST /fanout/hostcom_batch/preview, POST /fanout/{dispatch_id}/commit — preview and commit a hostcom fan-out
fanout.execute	GET /fanout/{dispatch_id} — poll fan-out status for any operation type
transactions.view	GET /sales/... — live sales data from a store lane
inventory.view	GET /inventory/... — live inventory data from a store lane
products.view	GET /products/... — live product data from a store lane
control.view	GET /control/... — live control reference data from a store lane
promotions.view	GET /promotions/... — live promotion data from a store lane
inventory-adjustments.create	Fan-out operation_type=inventory_adjustment — apply inventory adjustments across stores

Request minimal scopes

A service account that only generates hostcom files and dispatches them needs hostcom-batches.create, hostcom-batches.dispatch, and fanout.execute. Add installs.view if it also needs to enumerate your store network. Request transactions.view, inventory.view, etc. only for integrations that read live lane data.

Tenant Binding

Your OAuth client is bound to your organization at creation time. Every token it obtains carries your org's identity. The API enforces this binding on every request:

• You may only pass your own org's ID (or a descendant store org's ID) in X-Organization-Context
• You may only target your own stores with store_org_id query parameters
• Any attempt to act on an org outside your subtree returns 403 Forbidden

There is no way to escalate past this boundary with any combination of headers or parameters.

Token Management Best Practices

1. Cache tokens — Tokens are valid for the expires_in duration (typically 1 hour). Cache and reuse them rather than requesting a new token on every API call.
2. Refresh before expiry — Request a new token when the current one has fewer than 5 minutes remaining to avoid mid-operation expiry.
3. Server-side only — Never send your access token to the browser. All RORCex API calls should originate from your backend.
4. Request minimal scopes — Only include permissions your integration actually uses. Narrowing scope limits the blast radius if credentials are ever compromised.

Auth Error Responses

Status	Condition
401 Unauthorized	Authorization header missing, token malformed, token expired, or token_type is not service_account
403 Forbidden	Token is valid but does not carry the required permission for this endpoint, or the request targets an org outside your subtree

401 — Missing or invalid token

{
  "error": "Unauthenticated.",
  "message": "No valid Bearer token was provided."
}

401 — Wrong token type

{
  "error": "invalid_token_type",
  "message": "This endpoint requires a service_account token."
}

403 — Missing permission

{
  "error": "Forbidden.",
  "message": "Your token does not have the installs.view permission."
}

403 — Cross-org access attempt

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

---

Changelog

Date	Change
2026-06-11	Initial publication.