Authentication

Memoturn uses project-scoped API keys for every machine-to-server call. The same model works for REST, the TypeScript SDK, the CLI, and MCP. There is no token exchange, no OAuth, no refresh dance: paste a key, send it on the request, you’re authenticated.

Mint a key

1. Sign into the dashboard.
2. Open the project you want to authorize.
3. Click the API Keys tab → Issue key.
4. Optionally name the key (helps when revoking later: “ci/main”, “alice@laptop”).
5. Copy the key. It is shown once, then only the hash is stored.

Keys begin with mt_ and are ~40 characters. Treat them like passwords.

Headers

Every request needs an Authorization header. The project is always in the URL path — no X-Project-Id header required:

header	value
Authorization	Bearer <your mt_… key>

All project-scoped endpoints live under /v1/projects/{slug}/...:

# MCP endpoint
curl https://api.memoturn.ai/v1/projects/my-project/mcp \
  -H "Authorization: Bearer mt_…" \
  -d '{"jsonrpc":"2.0","method":"list_recent_turns","params":{},"id":1}'

# WebSocket subscribe
curl https://api.memoturn.ai/v1/projects/my-project/subscribe \
  -H "Authorization: Bearer mt_…"

The SDK and CLI set headers automatically once you pass the key. See their reference pages.

Scope

A key is bound to one project. It cannot read or write a different project’s data. Mint a separate key per project, or use a different sign-in.

The acting-user email is bound to the key at mint time (whoever was signed into the dashboard). Turns recorded with that key are stamped with the email automatically, so the dashboard’s Replay and Focus tabs can attribute work back to a person without you sending an actor field on every call.

Rotation

• Issue a new key before revoking the old one. There’s no overlap window when an active key is revoked.
• Revoke from the API Keys tab. The hash is removed from KV; subsequent requests with that key get 401 Unauthorized within seconds (Cloudflare KV propagation).
• Keys are not time-limited by default. Rotate on a cadence that matches your secret-management policy.

WebSocket auth

The same Authorization: Bearer … header authenticates the WebSocket subscription at wss://api.memoturn.ai/v1/projects/{slug}/subscribe.

If your client can’t send headers on the WS upgrade (browsers can’t), pass the key as a query param:

wss://api.memoturn.ai/v1/projects/{slug}/subscribe?token=mt_…

Query-param auth is the same KV lookup; it’s no less secure than the header. Avoid logging the URL.

Rate limits

Hosted plans rate-limit to 600 requests/minute per project. Bursts above that return 429 Too Many Requests with a Retry-After header.