Skip to main content
Mnemom supports four authentication paths — passkeys, password + MFA, SSO, and API keys — each mapped to the operations it is meant for. Sensitive actions are gated by AAL2 step-up: a fresh user-verification gesture within a short window, on top of the current session. This page is the operator-level reference; for the end-user passkey walkthrough, see Passkeys.
The auth overhaul (passkey + AAL2) is the current system. Earlier docs that describe Bearer-JWT-only or API-key-only access on all endpoints are superseded by the tiered model below.

​
Authentication methods at a glance

Passkeys are phishing-resistant (scoped to mnemom.ai, never presented to a wrong origin) and not a shared secret (Mnemom stores only the public half). They are the recommended default.
Headless agents (CI runners, containerised workers, server-side pipelines) cannot complete the browser-redirect flow. Use the OAuth 2.0 device-authorization grant instead — the agent obtains a short user_code, the operator approves it in a browser, and the agent polls the token endpoint to receive an access token.

​
Passkey enrollment

A passkey is a public/private keypair created by your device on enrollment, unlocked only by a biometric or PIN, and usable only at mnemom.ai. End-user steps:
  1. Sign in to the dashboard the normal way (password + MFA, or SSO).
  2. Open Settings → Account → Passkeys and click Add a passkey.
  3. Give it a friendly name (“MacBook Touch ID”, “YubiKey — office”).
  4. Confirm the device’s biometric / PIN.
  5. The passkey is live immediately; subsequent sign-ins can use it.
Enrolling on at least two devices (or one device that syncs via iCloud Keychain, Google Password Manager, 1Password, Bitwarden, etc.) prevents lockout from a single-device loss. See Passkeys for browser support, troubleshooting, and the full end-user flow.

​
AAL2 step-up

Sensitive actions — removing a passkey, rotating an API key, changing SSO enforcement, deleting an organization — require Authenticator Assurance Level 2 (AAL2): a user-verification gesture completed in the current flow, not reused from an older session. The step-up is presented inline: when an AAL2-protected action is attempted and the current session does not already carry an AAL2 claim, the dashboard prompts for a passkey gesture (or a TOTP code for password users, or an IdP re-assertion for SSO users). Passkey-minted sessions satisfy AAL2 for their lifetime — WebAuthn is inherently multi-factor under NIST SP 800-63B; for password and SSO users the gesture stamps the AAL2 claim on the session. Each WebAuthn step-up challenge is single-use and valid for 60 seconds. Actions that require AAL2 step-up:
  • Removing a passkey or adding a hardware authenticator
  • Creating, rotating, or revoking an API key
  • Changing SSO configuration or enforcement
  • Inviting or removing an org owner
  • Deleting an organization
  • Pausing, killing, or resuming an agent via the Containment API
  • Deleting your account

​
Session lifecycle

Dashboard sessions are issued as short-lived Supabase JWTs wrapped in an httpOnly, secure, same-site cookie. Rotation is automatic on the client; revocation is immediate on the server. Sessions expire after 7 days of inactivity — the idle window is re-upped on every authenticated request — and reach an absolute maximum lifetime of 30 days from the original sign-in, after which re-authentication is required. Sessions also end on explicit revocation. Active sessions are listed in Settings → Security → Active sessions with last-seen IP and user agent; each can be revoked individually. Server-side, sessions are revalidated on every protected request against the auth_sessions table. Stolen JWTs are not replayable past revocation.

​
API keys

API keys authenticate server-to-server calls against api.mnemom.ai and gateway.mnemom.ai. They use a capability-based scope vocabulary: each scope names what the key is allowed to do, defaults are least-privilege, and admin scopes are opt-in and gated by your role. The full deep dive on key management — including the side-by-side comparison of personal vs. organization keys, the per-scope reference table, and rotation/revocation flows — lives at API Keys. This section is the auth-flow summary.

​
Scope vocabulary at a glance

Default for new keys: ["gateway", "api:read", "api:write"]. Admin scopes are explicit opt-in; the API enforces a mint-time ceiling against your current role and re-checks on every request.

​
Creating an API key

​
Using an API key

API keys are rate-limited per plan tier (see API reference overview).

​
Legacy keys

Keys minted before May 2026 carry the legacy two-scope set ["gateway", "api"]. The auth gate aliases them to ["gateway", "api:read", "api:write"] at request time, so existing integrations continue to work unchanged. The dashboard renders them with a “legacy” annotation; rotation upgrades them to the canonical vocabulary. See API Keys → Legacy keys for the migration path.

​
Rotating an API key

Rotation is create-new-then-revoke-old, not an in-place swap. This gives you a window to roll callers over before the old key dies.
  1. Create the replacement key (AAL2 step-up required).
  2. Deploy the new key to your services.
  3. Verify traffic has shifted: the old key’s last-used timestamp should stop advancing.
  4. Revoke the old key.
Revocation is immediate. Any in-flight request using the revoked key receives HTTP 401 on its next call.

​
Rotating a provider API key bound to an agent

If you are rotating an agent’s provider key (Anthropic / OpenAI / Gemini) — not a Mnemom API key — see Rotating your agent’s API key. The flow preserves the agent’s ID, traces, and reputation.

​
Account recovery

If you lose all your passkeys and cannot complete MFA, use the password recovery path:
  1. On the sign-in page, click Forgot password?.
  2. Check email for the reset link (single-use, 15-minute TTL).
  3. Set a new password.
  4. Complete MFA enrollment or re-auth.
  5. Sign in.
  6. Re-enroll a fresh passkey from your new device.
Completing the password-recovery flow invalidates all existing sessions. If passkeys were enrolled at the time of the recovery, Mnemom logs an internal security-review event — surface it to support via the dashboard if it was not you. For SSO-enforced organizations, recovery goes through your IdP; Mnemom’s recovery path does not apply.

​
Responsible disclosure

Report suspected auth vulnerabilities via GitHub Security Advisories on the affected repository. Do not file public issues. We acknowledge within 48 hours and aim to provide a fix or mitigation within 7 days.

​
See also