# auth.md

**Mnemom API — Authentication Guide for Agents**

Mnemom is trust infrastructure 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.

## 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 + `agent_auth` profile | `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 (62 tools, 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, two things you might probe for are absent **by design**, not roadmap gaps:

- Mnemom does **not** mint its own OAuth 2.0 access tokens. Token issuance is delegated to **Supabase GoTrue**; the `authorization_endpoint` / `token_endpoint` / `jwks_uri` in our authorization-server metadata are the upstream Supabase endpoints, published for discovery only.
- Mnemom does **not** implement OAuth dynamic client registration (RFC 7591). The `agent_auth.register_uri` is Mnemom's own agent-registration endpoint (`POST /v1/agents`), not an OAuth client-registration endpoint.

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