> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Passkey sign-in, AAL2 step-up, session lifecycle, API key rotation, and account recovery for the Mnemom dashboard and API.

Mnemom supports four authentication paths — passkeys, password + MFA, SSO, and API keys — each mapped to the operations it is meant for. A small set of account-security actions are gated by **AAL2 step-up**: a fresh user-verification gesture on top of the current session. This page is the operator-level reference; for the end-user passkey walkthrough, see [Passkeys](/guides/passkeys). For how a CLI or a headless agent authenticates (as opposed to a human at the dashboard), see [API reference overview](/api-reference/overview#authentication) and the [OAuth device flow guide](/guides/oauth-device-flow).

***

## Authentication methods at a glance

| Method | Used for | AAL | Where to enroll |
| - | - | - | - |
| Passkey (WebAuthn / FIDO2) | Dashboard sign-in, SDK-issued sessions | AAL2 if the gesture is fresh | Settings → Account → Passkeys |
| Password + MFA (TOTP) | Dashboard sign-in, recovery path from lost passkeys | AAL2 when MFA is completed in the current flow | Settings → Security |
| SSO (Okta, Entra ID, Google Workspace) | Org-enforced dashboard sign-in | AAL1 by default; reaches AAL2 only via the same in-session step-up gesture other methods use | Org Settings → SSO |
| API key | Server-to-server API calls | N/A — bound to the org, scoped by role | Settings → API Keys or Org Settings → API Keys |

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.

<Note>
  **Headless agents** (CI runners, containerised workers, server-side pipelines) cannot complete the browser-redirect flow. Use the [OAuth 2.0 device-authorization grant](/guides/oauth-device-flow) 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.
</Note>

***

## 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](/guides/passkeys) for browser support, troubleshooting, and the full end-user flow.

***

## AAL2 step-up

A small set of destructive account-security actions require **Authenticator Assurance Level 2 (AAL2)**: a user-verification gesture completed in the current session, not carried over from an older one.

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). Passkey-minted sessions satisfy AAL2 for their lifetime — WebAuthn is inherently multi-factor under NIST SP 800-63B. AAL2 is currently a binary session property (once a session reaches AAL2 it stays there — there is no separate time-boxed re-auth window), and SSO sessions do not automatically inherit AAL2 from the IdP's own step-up state; an SSO user goes through the same in-session gesture as everyone else. Each WebAuthn step-up challenge is single-use and valid for 60 seconds.

Actions that require AAL2 step-up today:

* Removing a passkey
* Disabling MFA
* Revoking a session (your own, or all other sessions)

Other sensitive actions — API key management, SSO configuration, org membership and deletion, agent containment — are gated by role and org membership (see [Org Admin](/guides/org-admin)) rather than by a fresh AAL2 gesture.

***

## Session lifecycle

Dashboard sessions are issued as a short-lived signed access token wrapped in an httpOnly, secure, same-site cookie (`__Host-mnemom_session` on the live site). Rotation is automatic on the client; revocation is immediate on the server.

| Event | Effect |
| - | - |
| Sign-in (any method) | Access token issued carrying an `aal` claim (`aal1` or `aal2`); a revocable session record is registered server-side |
| AAL2 step-up | Session `aal` claim upgraded to `aal2` |
| Token refresh | Old JWT invalidated, new JWT issued with preserved claims |
| Sign-out | Session record deleted; all tokens derived from it fail verification |
| Password reset | All sessions for the user invalidated |
| Passkey removal | The specific credential invalidated server-side; other sessions are unaffected |
| Org role change | Affected user's sessions re-issue with new claims on next refresh |

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 against the session registry on every protected request. Stolen tokens are not replayable past revocation.

Signing in from a new device sends a notification email; that email carries a one-click, single-use revoke link so you can kill the new session without first signing back in yourself — useful if the new sign-in wasn't you.

### Sign-in throttling

Password and MFA-code attempts are throttled per account, on top of the per-IP limit. After 10 attempts for the same email (or the same pending MFA sign-in) from one network without a successful sign-in, or a much higher number across all networks, further attempts are held for 30 seconds, and the hold doubles with each attempt up to 15 minutes. A held attempt returns `429` with code `rate_limited` and a `Retry-After` header, whether or not the account exists. A successful sign-in clears the counter.

***

## 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](/guides/api-keys). This section is the auth-flow summary.

### Scope vocabulary at a glance

| Scope | Grants | Mintable by |
| - | - | - |
| `gateway` | Send LLM traffic through Mnemom's gateway worker. | Anyone |
| `api:read` | `GET` endpoints scoped to your identity. | Anyone |
| `api:write` | `POST`/`PUT`/`PATCH`/`DELETE` endpoints scoped to your identity. | Anyone |
| `admin:org` | Org-admin operations on orgs you own/admin. | Org owner / org admin |
| `admin:platform` | Mnemom-staff platform operations. | Mnemom staff only |

**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

<Steps>
  ### Sign in and open API keys

  **Settings → API Keys** (personal) or **Org Settings → API Keys** (organization).

  ### Pick capabilities

  The dialog has a Capabilities section (default scopes) and an Admin permissions section (opt-in, role-gated). Quick-pick presets ("Default", "Read-only", "Gateway-only") cover most cases.

  ### Copy the secret

  The full key is shown exactly once. Mnemom stores only the SHA-256 hash server-side; the raw key cannot be retrieved after creation. Store it in a secrets manager, never in source control.
</Steps>

### Using an API key

```bash theme={null}
curl https://api.mnemom.ai/v1/agents \
  -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY"
```

API keys are rate-limited per plan tier (see [API reference overview](/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](/guides/api-keys#legacy-keys-gateway-api) 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.
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](/guides/agent-key-rotation). 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). Open it in the same browser you requested it from; opened anywhere else, it shows a confirmation page naming the account before it signs you in.
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.

## Deleting your account

Account deletion is self-service and permanent: sign in and call `DELETE /v1/auth/delete-account` (cookie or Bearer auth; not available to API keys). It cancels any active subscription, permanently deletes your user identity, and unlinks (does not delete) any agents you claimed — they revert to unowned rather than disappearing. If you're the sole owner of an org that still has other members, deletion is refused until you transfer ownership or remove those members first.

***

## Responsible disclosure

If you discover a suspected auth vulnerability, see [Security and trust model § Responsible disclosure](/guides/security-trust-model#responsible-disclosure) for how to report it. Mnemom's passkey server-side verification is powered by [@simplewebauthn/server](https://github.com/MasterKale/SimpleWebAuthn).

***

## See also

* [Passkeys](/guides/passkeys) — End-user enrollment, browser support, troubleshooting
* [API reference overview](/api-reference/overview) — Base URL, auth headers, rate limits, error codes
* [Rotating your agent's API key](/guides/agent-key-rotation) — Provider-key rotation for an existing agent
* [Security and trust model](/guides/security-trust-model) — Full trust model spanning AAP, AIP, and the gateway
* [Safe House](/concepts/safe-house) — Request-pipeline view of how Safe House screens every agent transaction at four checkpoints (front door, back door, inside.autonomy, inside.integrity)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.