# auth.md

**Mnemom API — Authentication Guide for Agents**

Mnemom is the trust plane for AI agents. This document tells you, an automated client, exactly how to authenticate against the Mnemom API. It describes only what is real and reachable today. We publish what is real, not what is planned.

- **API base:** `https://api.mnemom.ai/v1`
- **Machine-readable contract:** `https://api.mnemom.ai/openapi.json` (OpenAPI 3.1)

If anything here disagrees with `openapi.json`, the OpenAPI document is authoritative.

## Programmatic / agent authentication

The API advertises two security schemes in its OpenAPI `securitySchemes`. Use whichever fits your client.

### 1. Bearer JWT

Send a JSON Web Token issued by Mnemom's identity provider, Supabase GoTrue.

```http
Authorization: Bearer <token>
```

- **Issuer (`iss`):** `https://vaqzyscwdtguoaksyglp.supabase.co/auth/v1`
- Verify and validate these tokens against the GoTrue authorization server (see Discovery below).

### 2. API key

Send a long-lived Mnemom API key.

```http
X-Mnemom-Api-Key: mnm_...
```

API keys are prefixed `mnm_`. Treat them as secrets; do not embed them in client-side code or commit them to source control.

### Example request

```http
GET /v1/agents HTTP/1.1
Host: api.mnemom.ai
Authorization: Bearer <token>
```

or

```http
GET /v1/agents HTTP/1.1
Host: api.mnemom.ai
X-Mnemom-Api-Key: mnm_...
```

## Browser sessions (the www / app site)

The Mnemom web app does **not** use either header above and does **not** store tokens in `localStorage`.

- Authentication is carried by an **HttpOnly `mnemom_session` cookie**, issued by the gateway at `gateway.mnemom.ai`.
- The browser sends it automatically on same-site API requests made with `credentials: 'include'`.
- Session bootstrap is `GET /v1/auth/session` (per ADR-024 / T3-3).

This scheme is for first-party browser clients. If you are an automated agent, use a Bearer JWT or an API key instead — you cannot obtain or replay the HttpOnly cookie.

## Agent registration

Registering an agent is a Mnemom-specific flow against the API — **not** OAuth dynamic client registration (RFC 7591). Authenticate the calls with a Bearer JWT or an API key (above).

- **Register:** `POST https://api.mnemom.ai/v1/agents`
  Body: `{ "name", "hash_proof", "card_json"?, "policy_yaml"?, "org_id"? }`, where `hash_proof` is the hex SHA-256 of `${apiKey}|${agentName}`. Returns `{ "id", "agent_hash", "name", ... }`.
- **Claim into an org:** `POST https://api.mnemom.ai/v1/agents/{agent_id}/claim` — body `{ "hash_proof", "org_id"? }`. Defaults to the caller's primary org.
- **Rotate the key:** `POST https://api.mnemom.ai/v1/agents/{agent_id}/rekey`.
- **Revoke / erase:** `DELETE https://api.mnemom.ai/v1/agents/{agent_id}` (or reversible `POST .../tombstone` then `POST .../restore`).
- **Possession proof:** once registered, an agent may additionally authenticate with `X-Mnemom-Agent-Proof: <64-hex sha256>`.

This flow is published as an `agent_auth` profile in the authorization-server metadata below, so agents can discover it without reading this page.

## OAuth for MCP clients (`api.mnemom.ai`)

The API origin runs a standards-based OAuth 2.0 authorization server for clients that connect to the control-plane MCP server (`https://api.mnemom.ai/mcp`). Its metadata is at `https://api.mnemom.ai/.well-known/oauth-authorization-server` (RFC 8414) and `issuer` is `https://api.mnemom.ai` — distinct from the Supabase-delegated `www` document described below. Discover everything from that document rather than hard-coding endpoints; what it advertises today:

- **Dynamic Client Registration (RFC 7591) is supported** for public clients. `POST https://api.mnemom.ai/v1/oauth/register` (`registration_endpoint`) with at least a `client_name`; register with `token_endpoint_auth_method: "none"` (no client secret). The `@mnemom/mnemom` CLI uses this to register a public client per login.
- **Endpoints:** `authorization_endpoint` `https://api.mnemom.ai/v1/oauth/authorize`, `token_endpoint` `https://api.mnemom.ai/v1/oauth/token`, `revocation_endpoint` `https://api.mnemom.ai/v1/oauth/revoke`, `device_authorization_endpoint` `https://api.mnemom.ai/v1/oauth/device_authorization`.
- **Grant types:** `authorization_code`, `refresh_token`, and the device grant `urn:ietf:params:oauth:grant-type:device_code` (for input-constrained / headless clients).
- **PKCE is required** — `code_challenge_methods_supported` is `["S256"]` only.
- **`token_endpoint_auth_methods_supported`** is `["none"]` (public clients).
- **Scopes:** `mcp:read`, `mcp:write`.

This server is for obtaining MCP access tokens via OAuth. For plain REST API calls you can still use a Bearer JWT or an `X-Mnemom-Api-Key` directly (above) without going through OAuth.

## Discovery

| What | URL | Spec |
|------|-----|------|
| Protected-resource metadata (this origin) | `https://www.mnemom.ai/.well-known/oauth-protected-resource` | RFC 9728 |
| Protected-resource metadata (API) | `https://api.mnemom.ai/.well-known/oauth-protected-resource` | RFC 9728 |
| API catalog | `https://www.mnemom.ai/.well-known/api-catalog` | RFC 9727 |
| OpenAPI contract | `https://api.mnemom.ai/openapi.json` | OpenAPI 3.1 |
| Authorization server (token issuance, live OIDC discovery) | `https://vaqzyscwdtguoaksyglp.supabase.co/auth/v1/.well-known/openid-configuration` | OIDC Discovery |
| Authorization server metadata — API origin (OAuth for MCP / agent clients, **DCR + device grant**) | `https://api.mnemom.ai/.well-known/oauth-authorization-server` | RFC 8414 |
| Authorization server metadata — www origin (`agent_auth` profile, Supabase-delegated) | `https://www.mnemom.ai/.well-known/oauth-authorization-server` | RFC 8414 |
| MCP server card | `https://www.mnemom.ai/.well-known/mcp/server-card.json` | MCP `server.json` |
| MCP server — control plane (mirrors the CLI) | `https://api.mnemom.ai/mcp` | MCP, streamable-HTTP |
| MCP server — docs search (read-only) | `https://docs.mnemom.ai/mcp` | MCP, streamable-HTTP |

**Token issuance is delegated to Supabase GoTrue.** Verify access tokens against the JWKS in the Supabase OIDC discovery document above. The `https://www.mnemom.ai/.well-known/oauth-authorization-server` document declares `issuer: https://www.mnemom.ai`, points its `authorization_endpoint` / `token_endpoint` / `jwks_uri` at that upstream Supabase IdP (Mnemom mints no OAuth tokens of its own), and carries an `agent_auth` block describing the agent-registration flow above.

## AAP attestation keys — NOT for verifying your access token

`https://api.mnemom.ai/v1/.well-known/jwks.json` publishes **Ed25519** keys used to verify Mnemom-signed **Agent Alignment Protocol (AAP)** attestation tokens.

These keys are **distinct from authentication**. Do **not** use them to verify your access token. Verify access tokens against the Supabase GoTrue `jwks_uri` exposed by the OIDC discovery document above.

## Model Context Protocol (MCP)

Mnemom operates **two** public MCP servers, both streamable-HTTP:

- **Control plane** — `https://api.mnemom.ai/mcp`. The trust-infrastructure API surface (Trust Ratings, Alignment & Protection Cards, governance signals, postures, teams, webhooks, API keys) exposed as MCP tools, mirroring the `mnemom` CLI command surface. Read tools (`get_agent`, `get_integrity_score`, `list_agents`, …) and mutation tools (`claim_agent`, `create_api_key`, `create_posture`, …) authenticate exactly as the REST API does — a **Bearer** JWT or an `X-Mnemom-Api-Key` (see above). `tools/list` is public; tool *execution* enforces the same authz as the equivalent REST call.
- **Docs search** — `https://docs.mnemom.ai/mcp`. Read-only. Two tools (`search_mnemom_docs`, `query_docs_filesystem_mnemom_docs`) over the documentation and the OpenAPI spec. No auth.

The control-plane server advertises a discoverable server card at `https://www.mnemom.ai/.well-known/mcp/server-card.json` (MCP `server.json` shape). Point any MCP client at the endpoint above.

## Deliberate non-features

To avoid misleading automated clients, note these design choices — not roadmap gaps:

- The **`www` authorization-server document** (`https://www.mnemom.ai/.well-known/oauth-authorization-server`) mints no tokens of its own: its `authorization_endpoint` / `token_endpoint` / `jwks_uri` are the upstream **Supabase GoTrue** endpoints, published for discovery, and it advertises no `registration_endpoint`. This is separate from the API-origin OAuth server above (`https://api.mnemom.ai/.well-known/oauth-authorization-server`), which **does** run its own `token_endpoint` for MCP access tokens and **does** support Dynamic Client Registration (RFC 7591). Read the metadata document for the origin you intend to use; do not assume the two are interchangeable.
- The `agent_auth.register_uri` in the `www` document points at Mnemom's agent-registration endpoint (`POST /v1/agents`); that is the agent-identity flow described above, distinct from RFC 7591 OAuth client registration (which lives at the API origin's `registration_endpoint`, `POST /v1/oauth/register`).

We publish what is real, not what is planned; material changes are announced at `https://www.mnemom.ai/changelog` and reflected here and in the agent-readiness manifest at `https://www.mnemom.ai/for-agents`.

## Contacts

- **Security / responsible disclosure:** security@mnemom.ai (see `https://www.mnemom.ai/.well-known/security.txt`)
- **Escalation:** alex@mnemom.ai