USM - User Session Management

USM is the trust layer for the stack. It issues sessions for people, validates those sessions on every API call, and supports long-lived API keys for non-human integrations. When a service asks, "Is this caller allowed to act right now?", the first stop is USM.

USM is designed to be simple and consistent. Sessions are created at login, have a sliding expiration window, and can be revoked on demand. API keys are designed for integrations such as middleware or automation, and they carry explicit roles just like a human user.

Service scope and boundaries

USM owns sessions and API keys. It does not create users (UAS) and it does not define org membership (OFM). It simply validates that a caller is allowed to act right now and returns the caller's identity and role context to downstream services.

Implemented feature breakdown (what exists today)

• Session lifecycle: create, validate/touch, get, list, close.
• Session controls: logout other devices and logout everywhere.
• Session caps: per-user max active session enforcement.
• Session status model: active and doomed; doom is terminal.
• Session listing: self-only listing with pagination and filters.
• Service accounts and API keys: org-bound keys with role-based permissions.
• API key lifecycle: create, list, validate, revoke, revoke-all for a service account, and org-wide revoke.
• API key policy: optional org-level max age policy enforced during validation.

How sessions are implemented (behavioral breakdown)

Session creation

1. A user authenticates via UAS credentials.
2. USM validates the credentials and user status via UAS.
3. A new session is created with a sliding expiration window.
4. The session is returned for use in downstream API calls.

Session validation

• Every API Gateway service calls USM to validate the session.
• Validation checks that the session is active, not expired, and not revoked.

Session listing and management

• A session can list only the sessions that belong to its user.
• Filters include status and additional list filters; pagination uses next_token.
• Logout other devices ends all sessions except the current one.
• Logout everywhere ends all sessions for the user.

Session caps

• USM enforces a maximum active session count per user.
• The cap is configurable per user through UAS configuration.

How API keys are implemented (behavioral breakdown)

Service accounts and roles

• API keys are issued to service accounts that belong to an org.
• Each key carries a role set that defines which actions it can perform.

Validation and org status gating

• API keys are validated on every API call just like sessions.
• Validation includes org status so downstream services can enforce write blocking when an org is not verified.

Revocation and rotation

• Keys can be revoked individually, per service account, or for an entire org.
• Rotation is manual: create a new key, then revoke the old key.

Optional expiry policy

• Orgs can set a maximum key age. Expired keys are rejected during validation.

Example use cases (extensive)

Daily login flow: A staff member signs in with UAS credentials and receives a session. That session is used to call OFM, PVM, MRS, or PMC. If the user resets their passcode, USM revokes existing sessions as part of recovery.

Device loss response: A staff member loses a laptop. They log in from a safe device and use logout everywhere to invalidate all other sessions.

Integration onboarding: A warehouse system needs read-only access to product data. A service account is created with a read-only role and an API key is issued. The key is used for automated calls, and the org can revoke it instantly if the integration is compromised.

Partner automation: A marketplace integration uses an API key to pull product data nightly. When the contract ends, the org revokes the key without affecting human users.

Org-wide key reset: A security incident triggers a blanket rotation of all service-account keys. The org revokes all keys at once and issues new ones to the integrations that remain trusted.

Example scenarios and acceptance criteria

Scenario 1: Session create and sliding expiration

• A user logs in and receives a session.
• The session is validated repeatedly during activity.
• Acceptance: the session remains active within the sliding window; expired sessions are rejected.

Scenario 2: Logout everywhere

• A user invokes logout everywhere after device loss.
• All sessions are revoked.
• Acceptance: every prior session is invalid; new sessions require re-authentication.

Scenario 3: API key validation with org gating

• An API key is issued for a service account.
• The org is parked or suspended.
• Acceptance: key validation reflects org status and downstream writes are blocked.

Scenario 4: Org-wide API key revoke

• An org revokes all service-account keys.
• Integrations attempt access with old keys.
• Acceptance: all revoked keys fail validation and are auditable.

Constraints and invariants

• Sessions are secrets and must be transmitted securely.
• USM never returns session secrets in response metadata.
• A session can only list or manage its own user's sessions.
• API keys are always tied to an organization and role set; they do not grant cross-org access.
• API keys are not automatically rotated; rotation is manual.
• Sessions do not rotate automatically; a session remains stable for its lifetime.

How USM fits with other services

UAS provides the identity and credential checks that allow USM to issue a session. Every API Gateway service (OFM, MRS, PVM, PMC) validates incoming sessions or API keys through USM and uses those results to enforce authorization.

Implemented vs planned

Implemented: session lifecycle, session revocation, per-user session caps, and service-account API keys with role-based permissions.

Planned: no additional public contract features are defined at this time. Any future changes will be additive and documented explicitly.

For exact request and response shapes, see the USM contract pages at https://doc.g3nretailstack.com/usm/.