Identity & Login

Create and protect tenant-bound accounts, rotating sessions, TOTP authenticators, federation bindings, profile projections, contact changes, account closure, request-signing keys, and signed workload identities through the authoritative Identity service.

BUSINESS CASES

Where this module fits

personal and corporate account onboarding
session issuance, refresh, inventory, and revocation
password recovery and authenticated password change
TOTP enrollment, recovery, and disablement
federated login and explicit account linking
profile and verified contact maintenance
retention-aware account closure
human API signing-key and machine workload-key lifecycle

PRIMARY CONSUMERS

Who integrates it

end-user applications
identity administrators
authentication and recovery agents
workload and agent platform operators

PREREQUISITES

What must exist first

configured and reachable Identity authority
tenant login or registration policy permitting the selected method
secure password, authenticator, provider, or Ed25519 private-key custody outside Hybrid-Chain
fresh purpose-bound TOTP step-up for protected changes
tenant administration authority and replacement-key proof for workload lifecycle actions

RECOMMENDED WORKFLOW

Compose the module safely.

01
resolve tenant brand, login policy, account type, and current legal terms
02
register and activate an account or complete an explicit federated login transaction
03
issue a short-lived session or refreshless workload bearer
04
read principal-derived profile and security projections
05
obtain a fresh purpose-bound step-up before sensitive changes
06
perform the exact mutation and immediately reconcile session, token, key, or lifecycle consequences

AGENT INTEGRATION

Machine-use boundaries

Never place passwords, activation or reset credentials, authenticator secrets, TOTP codes, recovery codes, OAuth codes, step-up tokens, access or refresh credentials, assertion JWTs, private keys, or provider tokens in URLs, prompts, logs, analytics, caches, or retained traces.
Distinguish account creation, activation, login, step-up, mutation, and session revocation: success in one phase never implies completion of another.
Password reset requests are intentionally enumeration resistant; always present the accepted response without inferring whether an account exists.
TOTP enrollment is pending until confirmation. Recovery codes are returned once, and authenticator disablement or any password change revokes all interactive sessions.
Federation state, authorization codes, PKCE material, refresh credentials, activation/reset credentials, step-up tokens, recovery codes, and assertion jti values are one-use; never replay them after an ambiguous result.
Human sessions rotate refresh credentials and workloads reassert with a new Ed25519 JWT. A workload bearer is bound to client, workspace, network, scope, expiry, and current public key.
Request-signing and workload-key rotation accepts public Ed25519 material and proof of possession only. Private keys never enter Hybrid-Chain; successful workload rotation revokes prior access tokens.
Use stable identifiers and exact snake_case fields from live OpenAPI. Re-read the authoritative resource after consequential changes and purge invalidated local credentials immediately.

Register only production-listed routes as executable tools, and re-fetch the deployed OpenAPI before generating or sending a request. Source-ready routes awaiting deployment are preparation references; planned contracts are non-executable.

MODULE CONTRACTS

Every mapped endpoint

Each operation states whether its request shape is authoritative in OpenAPI, reviewed as a planning profile, or intentionally left as an outline pending an owner schema.

POSTClose an account/api/v2/account-closure-requestsCreate an authenticated account-closure request after password verification and any required step-up check, preserving the optional reason without treating request acceptance as immediate erasure.›GETList sessions/api/v2/auth/sessionsList the authenticated identity's current and historical V2 client sessions.›POSTCreate session/api/v2/auth/sessionsVerify existing Hybrid credentials and issue short-lived V2 access plus a rotating refresh credential.›POSTRevoke session/api/v2/auth/sessions/{session_id}/revocationsRevoke the current session or use fresh step-up authorization to revoke another client session.›POSTDisable authenticator/api/v2/me/authenticator-disablementsRequire purpose-bound step-up or a single-use recovery code, disable TOTP, and revoke active sessions.›POSTBegin authenticator enrollment/api/v2/me/authenticator-enrollmentsCreate a bounded TOTP enrollment and return the enrollment secret once under no-store.›POSTConfirm authenticator enrollment/api/v2/me/authenticator-enrollments/{enrollment_id}/confirmationsVerify a live authenticator code, activate TOTP, and return single-view recovery codes.›POSTRegister account/api/v2/registrationsCreate an inactive tenant-bound account with server-side password hashing, versioned terms acceptance, and encrypted activation delivery.›GETGet account closure request/api/v2/account-closure-requests/{request_uuid}Return the authenticated subject's authoritative account-closure lifecycle state.›POSTCancel account closure request/api/v2/account-closure-requests/{request_uuid}/cancellationsCancel an eligible closure request after fresh authenticator verification when required.›GETGet login policy/api/v2/admin/identity/login-policyRead provider readiness and tenant login-method policy with administrator authority.›PUTUpdate login policy/api/v2/admin/identity/login-policyPublish tenant login-method policy with administrator authority and purpose-bound step-up authorization.›POSTBegin federated authorization/api/v2/auth/federation/{provider}/authorizationsCreate a one-time server-owned OAuth authorization-code and PKCE transaction for Google, Apple, or GitHub.›POSTExchange federated authorization/api/v2/auth/federation/{provider}/exchangesVerify and consume a provider authorization response once, then issue a Hybrid session or complete an explicit account link.›POSTRefresh session/api/v2/auth/session-refreshesRotate a single-use refresh credential and issue the next V2 credential pair.›POSTExchange workload assertion/api/v2/auth/workload-token-exchangesVerify a one-time Ed25519 private-key JWT assertion and issue a refreshless, network-bound scoped workload bearer with a 15-minute default and network-specific lifetime cap.›GETGet contact projection/api/v2/me/contactReturn the authenticated subject's email and phone verification projection.›POSTRequest email change/api/v2/me/contact/email-change-requestsAuthenticate a proposed email replacement and deliver a 15-minute one-time token to the new address.›POSTConfirm email change/api/v2/me/contact/email-change-requests/confirmConsume the one-time email token, atomically replace the address, and revoke active sessions.›POSTRequest phone change/api/v2/me/contact/phone-change-requestsAuthenticate a proposed E.164 phone replacement and deliver a 15-minute one-time SMS token.›POSTConfirm phone change/api/v2/me/contact/phone-change-requests/confirmConsume the one-time SMS token, atomically replace the phone, and revoke active sessions.›GETGet preferences/api/v2/me/preferencesReturn locale, timezone, language, base currency, theme, developer experience, Business Network mode, and workspace ordering preferences.›PUTUpdate preferences/api/v2/me/preferencesUpdate the complete submitted account preference subset through a signed mutation.›GETGet privacy settings/api/v2/me/privacyReturn visibility controls without embedding the full user record.›PUTUpdate privacy settings/api/v2/me/privacyUpdate visibility controls through a signed mutation.›GETGet core profile/api/v2/me/profileReturn identity, account type, display name, and names without contact, preference, privacy, or verification data.›PATCHUpdate core profile/api/v2/me/profileUpdate only the authenticated subject's personal or company names through a signed mutation.›GETGet verification summary/api/v2/me/verification-summaryReturn current assurance, decision, completion, and retention posture without evidence payloads.›GETGet workspace preferences/api/v2/me/workspaces/{workspace_uuid}/preferencesReturn the authenticated member's experience preferences for one workspace, including its default wallet environment.›PUTUpdate workspace preferences/api/v2/me/workspaces/{workspace_uuid}/preferencesSet or clear the authenticated member's default wallet environment for one workspace through a signed mutation.›POSTActivate account/api/v2/account-activationsConsume a one-time activation credential, activate the account, and return the canonical activation receipt.›GETList authentication events/api/v2/me/authentication-eventsList successful password and federated sign-ins with redacted device context and integrity-protected cursor pagination.›PUTChange password/api/v2/me/passwordRequire bearer authorization, current-password proof, conditional authenticator step-up, and revoke active sessions.›POSTRequest reset link/api/v2/password-reset-requestsApply the requested transition to reset link through the authoritative trust service boundary.›POSTReset password/api/v2/password-resetsApply the requested transition to reset password through the authoritative trust service boundary.›GETGet tenant brand/api/v2/tenant-brandReturn the authenticated tenant's presentation-safe names, theme, assets, links, and labels without exposing policy, credential, banking, registration, or infrastructure configuration.›POSTRegister request signing key/api/v2/security/signing-keysRegister an Ed25519 public JWK after proof of possession and purpose-bound step-up authorization.›GETList workload clients/api/v2/admin/identity/workload-clientsList tenant-scoped machine identities, public keys, delegated scopes, and lifecycle state.›POSTRegister workload client/api/v2/admin/identity/workload-clientsRegister an Ed25519 workload identity using proof of possession and purpose-bound administrator step-up.›POSTRevoke workload client/api/v2/admin/identity/workload-clients/{client_id}/revocationsRevoke a workload client and immediately invalidate all of its outstanding access tokens.›POSTRotate workload client/api/v2/admin/identity/workload-clients/{client_id}/rotationsRotate a workload client's public request-signing key using old-key authorization and new-key proof of possession.›GETList request signing keys/api/v2/security/signing-keysList public request-signing key metadata for the authenticated client.›POSTRevoke request signing key/api/v2/security/signing-keys/{key_id}/revocationsRevoke an active request-signing key after purpose-bound step-up authorization.›POSTCreate step up authorization/api/v2/security/step-upVerify a fresh authenticator code and issue a five-minute purpose-bound authorization.›