Authentication

Memoturn accepts two credentials. Project-scoped API keys are the simplest: paste a key, send it on the request, you’re authenticated. They work for REST, the TypeScript SDK, the CLI, and MCP, and they are the right choice for CI, scripts, and anything without a browser.

An MCP client can instead sign in through OAuth 2.1, so nobody pastes a key at all: the client discovers the authorization server from a 401, registers itself, and runs a browser consent flow. Claude Code, Cursor, VS Code, Codex, and Zed all take this path. See OAuth for MCP clients for the full flow, scopes, and PKCE requirements.

Mint a key

1. Sign into the dashboard.
2. Open the project you want to authorize.
3. Open Connect → Credentials → 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_live_ and are 51 characters. The prefix is deliberate: secret scanners index well-known prefixes, so a key pushed to a public repo gets flagged. 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_live_… 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_live_…" \
  -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_live_…"

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 Connect → Credentials. 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_live_…

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

Rate limits

The default rate limit is 600 requests/minute per project. Bursts above that return 429 Too Many Requests with a Retry-After header. Configurable via the rate limiter binding in wrangler.jsonc.