Request Context

Status: INTERIM (AS-BUILT partial; standardization in progress). Existing services require org/session context through documented headers and request bodies; placement varies by service.

Purpose

Define a consistent request context for all org-scoped services so callers can apply the same patterns across services.

Required context fields (business)

• Organization: required for all org-scoped operations.
• Logical facility: required for facility-scoped operations (inventory, sales, procurement).
• Channel: required when the operation is tied to a sales or procurement channel.
• Actor: required for auditability (user, service account, or system job identity).
• Context source: required (session, api_key, operator, or system); session/api-key contexts must include the corresponding fingerprint.
• Roles: resolved by OFM; used to authorize the action.
• Cost centre: optional attribution for billing and audit correlation.

Principles

• The request context is consistent across services even when payload structures differ.
• Facility-first operational views are required; org-wide views are analytics.
• Context fields are carried into events and audit trails; event envelopes include a request_context snapshot.
• A single request-context object should be used by SDKs, then mapped to per-service input placement (headers/body/query) to reduce integration errors.

Canonical request_context schema (contract)

Schema: /common/schemas/request-context.schema.json

{
  "orgcode": "ORG123",
  "org_guid": "ORG_GUID",
  "logical_guid": "LOGICAL_GUID",
  "channel_code": "WEB",
  "cccode": "ABCD-1234-EFGH",
  "actor": "user_guid:U123",
  "roles": ["pvv"],
  "context_source": "session",
  "session_fingerprint": "sf_abc123"
}

Required:

• orgcode
• actor
• context_source
• plus session_fingerprint when context_source=session
• plus api_key_fingerprint when context_source=api_key

Placement rules (where request_context lives)

The request_context object is used in eventing and audit trails. On HTTP surfaces:

• Auth: headers (x-session-guid / x-api-key) are canonical unless a service explicitly requires body auth.
• Org/facility/channel: may appear in headers or body depending on service (see /common/headers-identity.html).
• Request context fields must be consistent with header/body identity fields; mismatches are rejected.

Validation rules (baseline)

• orgcode required for org-scoped calls.
• logical_guid required for facility-scoped calls.
• channel_code required for channel-scoped calls.
• orgcode, logical_guid, and channel_code must refer to valid OFM records within the caller’s org.
• roles[] must be a subset of resolved roles for the caller; extra roles are rejected.
• context_source must reflect the caller credential type (session vs API key).

SDK guidance: request context builder

Recommended SDK flow:

1. Resolve auth context
   • Session: validate via USM (/usm/session/validate) → session_fingerprint.
   • API key: validate via USM (/usm/api_key/validate) → api_key_fingerprint.
2. Resolve org/roles
   • Call OFM POST /member/resolve with orgcode (and logical_guid if facility-scoped).
3. Build request_context
   • Populate orgcode, logical_guid, channel_code, cccode, actor, roles, context_source, and fingerprint.
4. Map to request placement
   • Headers: auth + x-orgcode (where required).
   • Body/query: org/facility/channel selectors as required by the service.

This keeps client code consistent even when services place identity fields differently.

Scope and gating matrix (business)

This matrix summarizes where org, facility, and channel context is required.

Service / Domain	Primary scope	Facility scoped?	Channel context?	Notes
UAS	Global identity	No	No	Operator-only actions; public stat uses credential check.
USM	Global sessions + org-bound API keys	No	No	API keys are org-scoped; downstream services enforce org status.
OFM	Org + facility	Yes	Yes (sales channels)	Defines org status, membership, and facility spine.
MRS	Org	Optional	Optional	Payload storage; org membership gating applies.
PVM	Org	No	Optional	Master product model; no facility writes.
PMC	Org	Yes (logical identity)	Yes	Published sellability per channel + logical facility.
ICS	Facility + org policy	Yes	Yes	Real-time stock and warehouse operations.
SCM	Facility	Yes	Yes (sales channel)	Orders reference sales-channel carts.
PCM	Facility	Yes	Yes (procurement channel)	Procurement worksheets drive POs.
PPM	Org with facility/channel overrides	Yes (overrides)	Yes	Temporal pricing and promotions.
CRM/Loyalty	Org	Optional	Optional	Customer and loyalty ledgers with context capture.
Influencer/Affiliate	Org	No	Yes	Attribution and earnings by channel.
Accounting/ERP	Org	Uses facility/channel dimensions	Yes	Exportable financial event views.
IPM	Org	No	Optional	Integration plane (webhooks, CDC, bulk jobs).
RBS	Org	No	Optional	Owner-only event subscriptions delivered to customer SQS queues.
External Master Data	Global reference plane	No	No	Operator-only direct Lambda + CLI access.

Context validation (business)

• Org context is required for any org-scoped operation.
• Logical facility context is required for facility-scoped operations; org-wide views are analytics.
• Channel context is required for channel-bound operations (sales or procurement).
• Context must be consistent: facility and channel must belong to the org.
• Cost-centre attribution is optional; if provided, it must be validated and carried into events.
• Where request_context is required, services validate it against the caller identity (header/body inputs): orgcode, logical_guid, channel_code, cccode, and context_source must match when present.
• Roles in request_context.roles must be a subset of resolved roles; unexpected roles yield invalid-input.

Related pages

• Headers & identity: /common/headers-identity.html
• Request builders: /common/request-builders.html
• Role matrix: /common/role-matrix.html
• Request context schema: /common/schemas/request-context.schema.json