> ## 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. # API Reference Overview > Authentication, base URL, error handling, and rate limits for the Mnemom API ## Base URL All API requests are made to: ``` https://api.mnemom.ai/v1 ``` The API is versioned at two levels: * **URL (`/v1/`)** — the API generation. Changes only for complete redesigns (infrequent). * **`X-Mnemom-Version: YYYY-MM-DD` header** — controls behavior within `/v1/`. Pin this for production stability. ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "X-Mnemom-Api-Key: " \ -H "X-Mnemom-Version: 2026-08-17" ``` If you omit `X-Mnemom-Version`, the **latest** behavior is used — fine for new integrations, but production systems (including AI agents) should pin to a specific date. Every response echoes the version used: ``` X-Mnemom-Version: 2026-08-17 ``` Current version: **`2026-08-17`**. Support window: 18 months per version. See the [Versioning Policy](/policy/versioning) for the canonical commitment (what we'll and won't change, deprecation cadence, the support-window contract), or the [API Versioning guide](/guides/api-versioning) for integration how-to. ## Authentication The Mnemom API resolves the calling principal from one of three sources, checked in this order: the session cookie, then an `Authorization: Bearer` token, then an API key. Pick the one that matches the caller, not the endpoint. For end-user sign-in (passkey, password + MFA, SSO), session lifecycle, and API-key rotation, see the [Authentication guide](/guides/authentication). Passkeys are the default dashboard sign-in method — see [Passkeys](/guides/passkeys) for browser support and enrollment. ### Session cookie (dashboard / SPA) Browser sessions at `mnemom.ai` (and `www.mnemom.ai`) authenticate via an HttpOnly, `Secure`, `SameSite=Lax` cookie — `__Host-mnemom_session` on the live site (host-locked; the bare `mnemom_session` name is used only on `http://localhost` in local development) — issued on sign-in by the API itself. The cookie is opaque to JavaScript — it holds an encrypted blob of the underlying session tokens, never a raw access token. ```bash theme={null} # Browser flow — the SPA does this transparently; you rarely call it directly. curl -X POST https://api.mnemom.ai/v1/auth/sign-in \ -H "Content-Type: application/json" \ -H "Origin: https://www.mnemom.ai" \ --cookie-jar cookies.txt \ -d '{"email":"you@example.com","password":"..."}' # Subsequent authenticated requests attach the cookie. curl https://api.mnemom.ai/v1/agents \ --cookie cookies.txt ``` The gateway auto-refreshes an expired access token server-side and rotates the cookie in the response. Passkey (WebAuthn / FIDO2) sign-in endpoints live at `/v1/auth/passkey/*` and return the same session cookie; MFA step-up is carried through `/v1/auth/mfa/*` and enterprise SSO through `/v1/auth/oidc/*`. Sensitive operations require **AAL2 step-up** — a fresh user-verification gesture within the current session; see the [Authentication guide](/guides/authentication#aal2-step-up) for the list of protected actions. This is the only auth pattern where `Access-Control-Allow-Credentials: true` matters — `fetch()` calls from the SPA must include `credentials: "include"`. ### Bearer token (CLI and OAuth/MCP clients) The Mnemom CLI and anything mimicking it use the classic `Authorization: Bearer ` header. `mnemom login` authenticates against Mnemom's own OAuth 2.1 authorization server — an authorization-code + PKCE flow via a local loopback redirect by default, or the [device-authorization grant](/guides/oauth-device-flow) with `--no-browser` — and stores the resulting scoped access token (prefixed `mcp_at_…`) and refresh token at `~/.mnemom/auth.json`; the CLI refreshes it automatically as it nears expiry. This is the same OAuth 2.1 server (and the same token shape) that issues access tokens to MCP clients — see [Connect over MCP](/mcp-clients#authentication). ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "Authorization: Bearer " ``` **How to get a Bearer token outside the CLI**: run `mnemom login` and read `~/.mnemom/auth.json`. Generating your own Bearer tokens from scratch is not supported — use an API key (below) for programmatic access. For a scripted client that wants a session without going through OAuth, `POST /v1/auth/login` accepts email + password and returns a bearer token pair directly in the JSON body (no cookie involved) — or, if you have a TOTP factor enrolled, `{ mfa_required: true, factor_id, mfa_token }`, which you complete with `POST /v1/auth/login/mfa`. `POST /v1/auth/refresh` exchanges the refresh token for a new pair. The API distinguishes an OAuth access token from this token type by its shape, so `Authorization: Bearer` accepts either without a separate header. ### API key For server-to-server and enterprise fleet management, authenticate with an API key: ```bash theme={null} curl https://api.mnemom.ai/v1/agents \ -H "X-Mnemom-Api-Key: " ``` **How to get an API key**: Generate one from the [Mnemom Dashboard](https://mnemom.ai/dashboard) under **Settings > API Keys**. API keys are scoped to your user account (or organization) and can be rotated at any time; creating and rotating a key only requires your normal signed-in session — see [Authentication — API keys](/guides/authentication#api-keys) for the rotation procedure. API keys are accepted on the great majority of endpoints — agent management, card and policy operations, integrity, webhooks, enforcement, reviews, teams, and deployments. This lets enterprise customers manage agent fleets programmatically without a user session. Billing management (`/v1/billing/*`) and account self-service operations (`GET /v1/auth/me`, `DELETE /v1/auth/delete-account`) are the notable exceptions: they require an end-user identity (cookie or Bearer) and do not accept an API key. API keys are hashed on our servers and cannot be retrieved after creation. Store your key securely when it is first displayed. ## Error format All error responses return a JSON body with a structured `error` object containing a stable `code` and a human-readable `message`: ```json theme={null} { "error": { "code": "error_code", "message": "Human-readable error message" } } ``` Branch on `error.code`, not `error.message` — codes are stable contract; messages may evolve. Some errors include an additional `details` object with structured per-code data. See [Errors](/api-reference/errors) for the full code taxonomy, retry semantics, and the Safe House verdict-to-status mapping. ### Common HTTP status codes | Status Code | Meaning | | - | - | | `400` | **Bad Request** — The request body is malformed or missing required fields. | | `401` | **Unauthorized** — Missing or invalid authentication credentials. | | `403` | **Forbidden** — Valid credentials but insufficient permissions for the requested resource. | | `404` | **Not Found** — The requested resource does not exist. | | `429` | **Too Many Requests** — Rate limit exceeded. Retry after the duration specified in the `Retry-After` header. | | `500` | **Internal Server Error** — Something went wrong on our end. Contact support if the issue persists. | ## Rate limits `/v1/*` requests are rate-limited **per client IP**, 100 requests/minute by default, in a 1-minute window. The `/v1/auth/*` surface (sign-in, passkey, MFA, SSO) is metered on an **independent** per-IP counter of the same default ceiling, so a burst of unrelated data-endpoint traffic from one IP can never starve that same IP's ability to authenticate. A small number of LLM-backed endpoints additionally enforce a per-user and per-org **hourly** budget on top of the per-minute ceiling above; their own documentation calls this out where it applies. Contact support to raise your rate-limit ceiling. ### Rate limit response Every `/v1/*` response carries `X-RateLimit-Limit` (the current per-minute ceiling) and `X-RateLimit-Reset` (Unix timestamp when the window resets). When the ceiling is exceeded, the API returns HTTP `429` with those two headers plus: | Header | Description | | - | - | | `Retry-After` | Seconds to wait before retrying | | `X-RateLimit-Remaining` | Always `0` on a 429 (not set on a successful response) | ```json theme={null} { "error": { "code": "rate_limited", "message": "Rate limit exceeded" } } ``` ## Idempotency Mutation endpoints accept an `Idempotency-Key` header. Send the same key on a retried request (network timeout, uncertain response, safe automatic retry after a `429`/`5xx`) and, if the original request already completed, you get back the exact same cached response instead of a second execution — the replayed response carries `Idempotent-Replay: true`. ```bash theme={null} curl -X POST https://api.mnemom.ai/v1/teams \ -H "X-Mnemom-Api-Key: " \ -H "Idempotency-Key: 3d4f7a2c-…" \ -H "Content-Type: application/json" \ -d '{"org_id": "org-abc123", "name": "Pipeline Alpha"}' ``` Reusing a key with a **different** request body is a conflict, not a replay. A concurrent in-flight request with the same key returns a retryable status rather than double-executing. ## Pagination List endpoints paginate with an opaque `cursor` query parameter and a `limit` query parameter (each endpoint documents its own default and maximum). The response includes a `next_cursor` field — pass it back as `cursor` to fetch the next page; omit `cursor` to start from the first page. A `null`/absent `next_cursor` means there are no more pages. ```bash theme={null} curl "https://api.mnemom.ai/v1/teams/{team_id}/roster-history?limit=50" \ -H "X-Mnemom-Api-Key: " ``` ## Endpoint documentation All endpoint documentation below is auto-generated from our OpenAPI specification. Each endpoint has a "Try It" button for interactive testing. ## API surface areas | Domain | Overview | Description | | - | - | - | | Reputation | [Reputation API](/api-reference/reputation-overview) | Trust scores, public pages, badges, verification | | Risk | [Risk API](/api-reference/risk-overview) | Risk assessment and scoring | | Policy | [Policy API](/api-reference/policy-overview) | Policy CRUD, evaluation, resolved policies | | Reclassification | [Reclassification API](/api-reference/reclassification-overview) | Violation reclassification, score recomputation, compliance export | | Intelligence | [Intelligence API](/api-reference/intelligence-overview) | Fault lines, risk forecasting, policy recommendations, transactions | | On-Chain | [On-Chain API](/api-reference/on-chain-overview) | Merkle root anchoring, score publishing, on-chain verification | | Safe House | [Safe House API](/api-reference/safe-house-overview) | Threat detection, quarantine management, canary credentials | | Unified Cards | [Unified Cards](/api-reference/unified-cards-overview) | Alignment and protection card CRUD across platform/org/team/agent scope | | Governance | [Governance guarantees](/api-reference/governance) | Audit, idempotency, schema identity, and webhook contracts shared across card mutations | | Agent Containment | Containment endpoints | Pause, kill, resume agents — kill-switch for rogue agents | | Teams | [Teams API](/api-reference/team-overview) | Team management, team reputation, team cards | | Webhooks | [Webhook event catalog](/api-reference/webhook-events) | Every event type your org's webhook endpoints can subscribe to | The Policy, Reclassification, Intelligence, and On-Chain APIs form the **[CLPI governance layer](/concepts/clpi)** — governance-as-code with policy enforcement, trust recovery, risk intelligence, and on-chain reputation anchoring. ## Versioning The API is versioned via the URL path (`/v1`). When breaking changes are introduced, a new version will be released under a new path (e.g., `/v2`). Non-breaking changes (new optional fields, new endpoints) are added to the current version without a version bump. We will provide advance notice and a migration guide before deprecating any API version. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.