User Session Management (USM)

Appearance

User Session Management (USM) ​

USM — User Session Management

Issuing, validating, closing, listing, and archiving sessions, plus managing org-bound service accounts and API keys. Base paths (custom domain):

  • Sessions: https://api.g3nretailstack.com/usm/session
  • Service accounts: https://api.g3nretailstack.com/usm/service_account
  • API keys: https://api.g3nretailstack.com/usm/api_key

Responses use { success, data?, error?, build, stats? } with build ID + UTC timestamp in the footer. Errors carry tags/messages; stats include request/build/latency/metrics and passthrough context when supplied.

Auth placement (important) ​

  • USM is body-auth-first: send session_guid (sessions) or api_key (API-key management) in the JSON body.
  • The only header-based auth on USM is x-api-key for POST /usm/api_key/validate.
  • This differs from most other services, which use canonical header auth; see /common/headers-identity.html.

Why POST for reads? ​

USM uses POST for read/list operations to keep credentials out of URLs, accept structured filters in JSON bodies, and keep the contract uniform. Treat USM reads as POST-only (no GET), and do not rely on caching semantics.

Surface map ​

  • Public API (API Gateway):
    • Sessions: POST /usm/session/create|validate|close|get|list|logout_other_devices|logout_everywhere
    • Service accounts: POST /usm/service_account/create|list|status
    • API keys: POST /usm/api_key/create|list|revoke|revoke_all|revoke_all_org|validate
  • Direct Lambda: not exposed directly; API Gateway fronts the handlers.
  • CLI: g3n usm ... calls the same API Gateway base. --profile required.
  • Pagination: list endpoints default limit 8, clamp 1–256, return opaque next_token cursors (split active/doomed cursors when status=all).
  • MCP: protocol doc at https://mcp.g3nretailstack.com/usm/PROTOCOL.md (mirrored here). MCP server: https://api.mcp.g3nretailstack.com/mcp.
  • OpenAPI: https://doc.g3nretailstack.com/usm/openapi.yaml

Session lifecycle (active → doomed → archived) ​

  • Create (session/create): email + passcode for a verified UAS user/email (email inputs canonicalized: trim + lowercase); enforces per-user cap (default 1024 or UAS override 32–8192). Returns session_guid, expiry, TTL fields, caption/label.
  • Validate/touch (session/validate): refreshes expiry when sliding TTL enabled; if expired or user/email falls out of verified, session is doomed with the matching reason.
  • Close (session/close): manual doom with reason closed.
  • Get (session/get): fetch by guid; optional archived lookup.
  • List (session/list): by caller (requires active session_guid), status filter (active|doomed|all), pagination, label/caption filters, optional archived listing with date bounds.
  • Doom reasons: ttl-expired, closed, user-suspended, user-doomed, email-unverified, email-doomed, manual. doomed_at_utc is always set. Archived copies remain retrievable when include_archived=true.

Quick start (happy path) ​

  1. session/create with verified email/passcode, optional caption/label/TTL overrides.
  2. Use session_guid on downstream calls that need auth.
  3. Periodically session/validate to keep sliding TTL alive (when enabled).
  4. session/close on logout; session/get or session/list for audit.

Service accounts + API keys (issuance guidelines) ​

  • Create one service account per integration instance (e.g., a specific Shopify store / POS connector deployment) so you can kill-switch one integration without impacting others.
  • Grant only the minimal roles needed (pvv, pma, vca); avoid owner for external connectors.
  • Create one API key per environment (prod/staging) and store the secret securely; the full api_key is returned only once on api_key/create.
  • Use x-api-key on downstream service calls; keep orgcode consistent with the key’s org (cross-org requests are rejected with 404 not-found).
  • For emergency response:
    • Org-wide compromise: api_key/revoke_all_org (invalidates all keys in the org created before the marker).
    • Single integration compromise: api_key/revoke_all (service-account marker), or doom the service account (terminal).
  • Prefer human sessions (session_guid) only for interactive admin flows (creating/listing/revoking keys); do not embed human sessions in long-lived automation.

Error tags (representative) ​

  • invalid-passcode, user-not-verified, email-not-verified, too-many-sessions, session-cap-invalid, session-not-found, session-doomed, ttl-expired, user-suspended, user-doomed, email-unverified, email-doomed, invalid-status, validation-error, internal-error.

See Surfaces for request/response examples, pagination patterns, and CLI usage.