User Session Management (USM)

Appearance

API Calls ​

Base: https://api.g3nretailstack.com/usm

Source of truth: /internal-docs/usm-openapi.yaml → /usm/openapi.yaml

Notes: samples are schema-derived placeholders. Replace placeholder values (ORGCODE, SESSION_GUID, etc.) with real values.

Inventory ​

MethodPathSummaryRequest schemaResponse schema
POST/api_key/createCreate an API key for a service account (secret returned once)UsmApiKeyCreateRequestUsmApiKeyCreateSuccess
POST/api_key/listList API keys for a service account (org owner only)UsmApiKeyListRequestUsmApiKeyListSuccess
POST/api_key/policy_setSet org-level API key policy (expiry) (org owner only)UsmApiKeyPolicySetRequestUsmApiKeyPolicySetSuccess
POST/api_key/revokeRevoke (doom) an API key (org owner only)UsmApiKeyRevokeRequestUsmApiKeyRevokeSuccess
POST/api_key/revoke_allRevoke all keys for a service account (marker; org owner only)UsmApiKeyRevokeAllRequestUsmApiKeyRevokeAllSuccess
POST/api_key/revoke_all_orgRevoke all API keys across the org (marker; org owner only)UsmApiKeyRevokeAllOrgRequestUsmApiKeyRevokeAllOrgSuccess
POST/api_key/validateValidate an API keyUsmApiKeyValidateRequestUsmApiKeyValidateSuccess
POST/service_account/createCreate a service account (org owner only)UsmServiceAccountCreateRequestUsmServiceAccountCreateSuccess
POST/service_account/listList service accounts for an org (org owner only)UsmServiceAccountListRequestUsmServiceAccountListSuccess
POST/service_account/statusDoom a service account (revokes all keys)UsmServiceAccountStatusRequestUsmServiceAccountStatusSuccess
POST/session/closeClose a session (doom as closed)UsmSessionCloseRequestEnvelope
POST/session/createCreate a new session (email + passcode)UsmSessionCreateRequestEnvelope
POST/session/getGet session metadata (optionally include archived)UsmSessionGetRequestUsmSessionGetSuccess
POST/session/listList sessions for the caller (self-only)UsmSessionListRequestUsmSessionListSuccess
POST/session/logout_everywhereLogout everywhere (revoke all sessions)UsmSessionLogoutEverywhereRequestUsmSessionLogoutEverywhereSuccess
POST/session/logout_other_devicesLogout other devices (doom other active sessions)UsmSessionLogoutOtherDevicesRequestUsmSessionLogoutOtherDevicesSuccess
POST/session/validateValidate a session (and refresh sliding TTL)UsmSessionValidateRequestEnvelope

Call details ​

POST /api_key/create ​

Purpose: Create an API key for a service account (secret returned once)

Notes: Create an API key for a service account (secret returned once). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmApiKeyCreateRequest Response schema: UsmApiKeyCreateSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "service_account_guid": "string"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "api_key_id": "API_KEY",
    "api_key_fingerprint": "API_KEY",
    "service_account_guid": "string",
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "status": "active",
    "caption": "Example caption",
    "created_at": "2026-01-01T00:00:00Z",
    "api_key": "API_KEY"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/create",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/list ​

Purpose: List API keys for a service account (org owner only)

Notes: List API keys for a service account (org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95 300ms).

Request schema: UsmApiKeyListRequest Response schema: UsmApiKeyListSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "service_account_guid": "string"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "api_keys": [
      {
        "api_key_id": "API_KEY",
        "api_key_fingerprint": "API_KEY",
        "service_account_guid": "string",
        "orgcode": "ORGCODE",
        "org_guid": "ORG_GUID",
        "status": "active",
        "caption": "Example caption",
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/list",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/policy_set ​

Purpose: Set org-level API key policy (expiry) (org owner only)

Notes: Set org-level API key policy (expiry) (org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmApiKeyPolicySetRequest Response schema: UsmApiKeyPolicySetSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "api_key_max_age_seconds": "API_KEY"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/policy_set",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/revoke ​

Purpose: Revoke (doom) an API key (org owner only)

Notes: Revoke (doom) an API key (org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmApiKeyRevokeRequest Response schema: UsmApiKeyRevokeSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "api_key_id": "API_KEY"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "api_key_id": "API_KEY",
    "api_key_fingerprint": "API_KEY",
    "service_account_guid": "string",
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "status": "active",
    "caption": "Example caption",
    "created_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/revoke",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/revoke_all ​

Purpose: Revoke all keys for a service account (marker; org owner only)

Notes: Revoke all keys for a service account (marker; org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmApiKeyRevokeAllRequest Response schema: UsmApiKeyRevokeAllSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "service_account_guid": "string"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "service_account_guid": "string",
    "revoke_before_utc": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/revoke_all",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/revoke_all_org ​

Purpose: Revoke all API keys across the org (marker; org owner only)

Notes: Revoke all API keys across the org (marker; org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmApiKeyRevokeAllOrgRequest Response schema: UsmApiKeyRevokeAllOrgSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "revoke_before_utc": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/revoke_all_org",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /api_key/validate ​

Purpose: Validate an API key

Notes: Validate an API key. Session/API-key operations use body auth; follow the USM surface placement rules. Route class Tier C (p95 150ms, p99 400ms).

Request schema: UsmApiKeyValidateRequest Response schema: UsmApiKeyValidateSuccess

Sample request (schema-derived)

json
{
  "api_key": "API_KEY",
  "actor": "string",
  "reason": "example"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "principal_type": "service_account",
    "api_key_id": "API_KEY",
    "api_key_fingerprint": "API_KEY",
    "service_account_guid": "string",
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "org_status": "active",
    "roles": [
      "string"
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /api_key/validate",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /service_account/create ​

Purpose: Create a service account (org owner only)

Notes: Create a service account (org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmServiceAccountCreateRequest Response schema: UsmServiceAccountCreateSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "roles": [
    "pvv"
  ]
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "service_account_guid": "string",
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "status": "active",
    "roles": [
      "pvv"
    ],
    "caption": "Example caption",
    "created_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /service_account/create",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /service_account/list ​

Purpose: List service accounts for an org (org owner only)

Notes: List service accounts for an org (org owner only). Session/API-key operations use body auth; follow the USM surface placement rules. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95 300ms).

Request schema: UsmServiceAccountListRequest Response schema: UsmServiceAccountListSuccess

Sample request (schema-derived)

json
{
  "orgcode": "ORGCODE"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "service_accounts": [
      {
        "service_account_guid": "string",
        "orgcode": "ORGCODE",
        "org_guid": "ORG_GUID",
        "status": "active",
        "roles": [
          {}
        ],
        "caption": "Example caption",
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /service_account/list",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /service_account/status ​

Purpose: Doom a service account (revokes all keys)

Notes: Doom a service account (revokes all keys). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier A (p95 500ms).

Request schema: UsmServiceAccountStatusRequest Response schema: UsmServiceAccountStatusSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "orgcode": "ORGCODE",
  "service_account_guid": "string",
  "status": "doomed"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "service_account_guid": "string",
    "orgcode": "ORGCODE",
    "org_guid": "ORG_GUID",
    "status": "active",
    "roles": [
      "pvv"
    ],
    "caption": "Example caption",
    "created_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /service_account/status",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/close ​

Purpose: Close a session (doom as closed)

Notes: Close a session (doom as closed). Session/API-key operations use body auth; follow the USM surface placement rules. Route class Tier B (p95 300ms).

Request schema: UsmSessionCloseRequest Response schema: Envelope

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "session_guid": "SESSION_GUID",
    "user_id": "USER_ID",
    "status": "doomed",
    "doom_reason": "example",
    "doomed_at_utc": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/close",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/create ​

Purpose: Create a new session (email + passcode)

Notes: Create a new session (email + passcode). Session/API-key operations use body auth; follow the USM surface placement rules. If this updates a revisioned record, expected_revision is required (428 if missing; 409 on mismatch). Route class Tier B (p95 300ms).

Request schema: UsmSessionCreateRequest Response schema: Envelope

Sample request (schema-derived)

json
{
  "email": "user@example.com",
  "passcode": "CODE1"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "session_guid": "SESSION_GUID",
    "user_id": "USER_ID",
    "status": "active",
    "expires_at_utc": "2026-01-01T00:00:00Z",
    "ttl_seconds": 0,
    "ttl_refresh_enabled": false,
    "caption": "Example caption"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/create",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/get ​

Purpose: Get session metadata (optionally include archived)

Notes: Get session metadata (optionally include archived). Session/API-key operations use body auth; follow the USM surface placement rules. Route class Tier B (p95 300ms).

Request schema: UsmSessionGetRequest Response schema: UsmSessionGetSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "session_guid": "SESSION_GUID",
    "user_id": "USER_ID",
    "status": "active",
    "expires_at_utc": "2026-01-01T00:00:00Z",
    "last_touched_at": "2026-01-01T00:00:00Z",
    "ttl_seconds": 0,
    "ttl_refresh_enabled": false,
    "caption": "Example caption",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/get",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/list ​

Purpose: List sessions for the caller (self-only)

Notes: Lists sessions for the user who owns the caller session_guid. Notes: - Requires an active session. - Accepts session_guid in body or via header x-session-guid.

Request schema: UsmSessionListRequest Response schema: UsmSessionListSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID",
  "status": "active",
  "limit": 8
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "sessions": [
      {
        "session_guid": "SESSION_GUID",
        "user_id": "USER_ID",
        "status": "active",
        "expires_at_utc": "2026-01-01T00:00:00Z",
        "last_touched_at": "2026-01-01T00:00:00Z",
        "ttl_seconds": 0,
        "ttl_refresh_enabled": false,
        "caption": "Example caption",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ]
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/list",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/logout_everywhere ​

Purpose: Logout everywhere (revoke all sessions)

Notes: Sets a per-user revoke marker and best-effort dooms active sessions. All sessions created before the revoke marker are rejected on validate and list with reason revoked.

Request schema: UsmSessionLogoutEverywhereRequest Response schema: UsmSessionLogoutEverywhereSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "user_id": "USER_ID",
    "revoke_before_utc": "2026-01-01T00:00:00Z",
    "doomed_sessions": 0,
    "scanned_active_sessions": 0
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/logout_everywhere",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/logout_other_devices ​

Purpose: Logout other devices (doom other active sessions)

Notes: Dooms all other active sessions for the user who owns the caller session_guid.

Request schema: UsmSessionLogoutOtherDevicesRequest Response schema: UsmSessionLogoutOtherDevicesSuccess

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "user_id": "USER_ID",
    "doomed_sessions": 0,
    "scanned_active_sessions": 0,
    "skipped_current_session": false
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/logout_other_devices",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}

POST /session/validate ​

Purpose: Validate a session (and refresh sliding TTL)

Notes: Validate a session (and refresh sliding TTL). Session/API-key operations use body auth; follow the USM surface placement rules. Route class Tier C (p95 150ms, p99 400ms).

Request schema: UsmSessionValidateRequest Response schema: Envelope

Sample request (schema-derived)

json
{
  "session_guid": "SESSION_GUID"
}

Sample response (shape-only)

json
{
  "success": true,
  "data": {
    "session_guid": "SESSION_GUID",
    "user_id": "USER_ID",
    "status": "active",
    "expires_at_utc": "2026-01-01T00:00:00Z",
    "ttl_seconds": 0,
    "ttl_refresh_enabled": false,
    "caption": "Example caption",
    "last_touched_at": "2026-01-01T00:00:00Z"
  },
  "build": {
    "build_id": "MONDAY-0000000000"
  },
  "stats": {
    "call": "POST /session/validate",
    "service": "usm",
    "timestamp_utc": "2026-01-01T00:00:00Z"
  }
}