Headers and Identity Cheat Sheet

Auth Placement Exceptions

USM and UTL use body auth (session_guid in JSON body), not header auth. All other org-scoped services use x-session-guid or x-api-key headers as canonical. See the Exceptions table below.

This page is a one-screen reference for where identity fields go (headers vs body vs query). It does not replace per-service docs; when in doubt, follow the service's surfaces page.

Quick rules

• GET: use query parameters for inputs, headers for auth and tenancy. Do not send JSON bodies on GET.
• POST: use JSON body for inputs. Org-scoped services use header auth (x-session-guid or x-api-key) with body auth accepted only when documented. Exceptions: USM and UTL require body auth.
• If both session_guid and api_key are provided, the session is authoritative and the API key is ignored.
• Never send session_guid or api_key in query strings.

Canonical placement rules (authoritative)

Sessions

• Header is canonical: x-session-guid on API Gateway routes (GET and POST).
• Body/session_guid is accepted only when documented.
• USM uses body auth for session creation and management.

API keys

• Header is canonical: x-api-key on API Gateway routes.
• Body/api_key is accepted only when documented.
• API keys are org-scoped; the request orgcode must match the key’s org.

Org scoping

• Header: x-orgcode is canonical for most org-scoped services (PVM/PMC/ICS/SCM/PCM/PPM/CRM/Influencer/Accounting/IPM/RBS/UTL).
• Body: some services keep org identity in the body (OFM, and certain MRS calls). Always follow the service surface page.
• If both header + body org identifiers are present, they must match or the request fails (context_mismatch).

Precedence rules

1. If both session and API key are present, session wins (API key ignored).
2. If both header and body auth are present, header wins (body ignored), unless the service explicitly states otherwise.
3. If header and body org identifiers disagree, the request fails.

Exceptions (explicit)

Service	Exception
USM	Body auth is canonical; headers are not required.
UTL	Body session_guid is required; header auth not used.
OFM	Org identity lives in body (org_guid/orgcode); headers are auth only.
MRS	Org identity is query on GET and body on POST; auth is header-only.

Request headers (API Gateway)

• x-orgcode: org context for org-scoped services (required by PMC; accepted by PVM). Some services keep org identity in the body instead of headers (OFM, MRS).
• x-session-guid: user session token for protected routes (canonical on GET).
• x-api-key: service-account token for protected routes (org-bound).
• x-logical-guid: logical facility context for facility-scoped operations (ICS, PCM, SCM operational routes). Required where documented per-route in the OpenAPI spec.
• x-channel-code: sales channel context (required where documented per-route in the OpenAPI spec).
• x-cccode: optional cost attribution. If a body field cccode is also provided, the values must match. Exception: OFM treats x-cccode as telemetry only and does not require it to match domain cccode inputs.

Response headers

• X-API-Version: date-based API version stamp (e.g., 2026-03-04). Present on every response from all 20 services. Log this alongside stats.build.build_id for debugging. See /common/versioning-compat.html for the versioning policy and future Sunset/Deprecation headers.

Service placement matrix (API Gateway)

UAS (public)

• POST /uas/stat
• Auth: email + passcode in JSON body (no session header).
• Optional x-cccode header or body cccode.

Example:

curl -sS "https://api.g3nretailstack.com/uas/stat" \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","passcode":"Abcd!234"}'

USM (public)

• All endpoints are POST with JSON body.
• Auth is credentialed by body fields (email/passcode) or session/API-key inputs in the body, depending on the endpoint.
• POST /usm/api_key/validate also accepts x-api-key for downstream service use.

UTL (tenant offboarding)

• All tenant endpoints are POST with JSON body.
• Auth: session_guid is required in the JSON body (UTL does not use header auth).

OFM (org/facility)

• All endpoints are POST with JSON body.
• Auth: canonical x-session-guid or x-api-key headers. Body session_guid / api_key are accepted for compatibility.
• Org identity lives in the body (orgcode, org_guid, logical_guid), per endpoint.

MRS (metarecords)

• Auth: headers only (x-session-guid or x-api-key).
• Org identity: orgcode in query on GET, orgcode in JSON body on POST.

GET example:

curl -sS -G "https://api.g3nretailstack.com/mrs/record/get" \
  -H "x-session-guid: $SESSION_GUID" \
  --data-urlencode "orgcode=$ORGCODE" \
  --data-urlencode "container=images" \
  --data-urlencode "record_id=$RECORD_ID"

PVM (products/vendors)

• GET: auth in headers (x-session-guid or x-api-key). Org in x-orgcode or query orgcode.
• POST: canonical auth in headers (x-session-guid or x-api-key). Body session_guid / api_key accepted for compatibility. Org in body orgcode or header x-orgcode.

GET example:

curl -sS -G "https://api.g3nretailstack.com/pvm/variant/get" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  --data-urlencode "variant_id=$VARIANT_ID" \
  --data-urlencode "style_id=$STYLE_ID"

PMC (publish control)

• GET: auth and org are headers only (x-orgcode plus x-session-guid or x-api-key).
• POST: headers are canonical; body session_guid/api_key accepted for convenience. x-orgcode remains required in headers.

GET example:

curl -sS -G "https://api.g3nretailstack.com/pmc/product/get" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  --data-urlencode "product_id=$PRODUCT_ID"

Direct Lambda actions

Direct Lambdas accept JSON payloads (no query strings). If a direct Lambda expects session_guid or orgcode, pass them in the payload as documented for that action.

Troubleshooting

If a call returns 404 not-found but you suspect the record exists, see the anti-enumeration checklist: /common/troubleshooting.html.