Playbooks

Playbooks are standard operating procedures (SOPs) for USM. Use calls.md for payload shape and required fields.

Surface availability (explicit)

• API Gateway: Available.
• Direct Lambda: Not offered.
• CLI: Available (g3n usm ..., API Gateway).
• MCP: Available.

Playbook: Session lifecycle (issue → validate → close)

Goal: Issue a session for a verified user, keep it alive while active, and close it cleanly.

Why this sequence:

• USM enforces per-user session caps and status gating at create time.
• Session validity changes when UAS user/email status changes or TTL expires.

Preconditions

• A verified user + primary email in UAS.
• Email + passcode for session creation.

SOP (happy path)

1. Confirm user status (UAS stat or direct userSnapshot).
   • Reason: USM will reject unverified users or emails.
2. Create session (POST /usm/session/create).
   • Reason: issues session_guid, TTL, and expiry fields.
3. Persist session details (store session_guid, expires_at_utc, ttl_refresh_enabled).
   • Reason: downstream calls require the session, and expiry drives refresh cadence.
4. Touch/validate session (POST /usm/session/validate) on activity.
   • Reason: refreshes sliding TTL when enabled and detects invalidation.
5. Audit (POST /usm/session/get or POST /usm/session/list) as needed.
   • Reason: confirm status and surface archived sessions when investigating issues.
6. Close session (POST /usm/session/close) on logout.
   • Reason: ensures a terminal doomed status and prevents reuse.
7. Security response (POST /usm/session/logout_other_devices or logout_everywhere) if compromise is suspected.

Outputs

• Active session for valid users; terminal doomed session on logout.
• Audit visibility via get/list.

Failure modes / remediation

• invalid-passcode / user-not-verified: re-verify user/email in UAS; retry create.
• too-many-sessions: close old sessions or raise user cap in UAS (userConfigSet).
• session-doomed / ttl-expired: create a new session.

Cross-service relationships

• UAS: provides verified user/email and passcode policy enforcement.
• All org-scoped services: use session_guid for auth.

Playbook: Service account + API key lifecycle

Goal: Create a least-privilege service account and issue API keys for automation.

Why this sequence:

• Service accounts isolate integrations; keys are revocable without impacting humans.
• API keys are returned only once; you must capture them at creation time.

Preconditions

• Owner or authorized admin session for the org.
• A defined role set for the integration (e.g., read-only vs publish).

SOP (happy path)

1. Create service account (POST /usm/service_account/create).
   • Reason: binds an integration identity to the org with roles.
2. List service accounts (POST /usm/service_account/list) to confirm creation.
   • Reason: inventory and audit readiness.
3. Create API key (POST /usm/api_key/create).
   • Reason: issues the api_key secret and metadata; capture the secret immediately.
4. Validate key (POST /usm/api_key/validate or header x-api-key).
   • Reason: confirm roles + org binding before using in production.
5. Use key downstream (x-api-key on org-scoped APIs).
   • Reason: headless automation should not use human sessions.
6. Revoke key (POST /usm/api_key/revoke) or rotate on schedule.
   • Reason: minimize exposure and support key rotation.
7. Incident response (POST /usm/api_key/revoke_all or revoke_all_org).
   • Reason: contain compromise quickly.

Outputs

• Active API key tied to a service account.
• Audit trail through key list/get endpoints.

Failure modes / remediation

• not-found on validate: ensure you captured the key value exactly once.
• forbidden/unauthorized: check roles assigned to the service account.

Cross-service relationships

• All org-scoped services accept USM API keys for auth.