Access

Two parallel auth flows let third parties drive memo's tool surface (MCP, the same surface the owner UI uses). Both end at the same place — a bearer token that /api/mcp accepts — but the issuance, lifetime, and rotation differ.

Personal Access Tokens#

Lifecycle#

1. Create. Visit /<your-username>/settings/tokens, click + New token, name it, tick the scopes, optionally set an expiry. The raw value — mp_<16-char public id>_<32-byte base64url secret> — is shown exactly once in a reveal modal with a clipboard-copy button.
2. Use. Send as Authorization: Bearer mp_… on every /api/mcp request. memo hashes the raw value with sha256, does a timing-safe compare against the stored token_hash, and bumps last_used_at on a hit.
3. Revoke. Click Revoke on the same page. We set revoked_at = now() atomically; subsequent requests return 401 immediately.

Scopes#

Scope checks happen inside every tool handler; tools throw unauthorized if the bearer doesn't carry the scope they need. The MCP endpoint returns this as JSON-RPC error code -32001.

Token format details#

mp_<16 base62 chars (public id)>_<43 base64url chars (32-byte secret)>

We store:

• tokenHash — sha256 of the full raw token (no salting needed; the secret is 32 random bytes).
• tokenPrefix — mp_<first 8 chars of public id>… — what we show in lists so owners can recognise tokens at a glance without leaking the secret.

That's enough to do a single-row indexed lookup on the hash and verify with timingSafeEqual (defence-in-depth — the DB equality already proves it).

OAuth 2.0 + PKCE#

Memo speaks RFC 6749 (Authorization Code), RFC 7636 (PKCE, S256 only), RFC 7591 (Dynamic Client Registration), RFC 7009 (Revocation), RFC 8414 (AS metadata), RFC 8707 (Resource Indicators), and RFC 9728 (Protected Resource Metadata).

That alphabet soup matters because claude.ai's "Add custom MCP" walks every one of those specs in order. If we only implemented the first three, the connector flow would silently fall apart at step 1 (the resource-metadata pointer is what tells claude.ai which authorize server to ask).

The flow (annotated)#

┌──────────────┐                                       ┌─────────────┐
│  claude.ai   │                                       │    memo     │
└──────┬───────┘                                       └──────┬──────┘
       │  POST /api/mcp (no bearer)                           │
       ├─────────────────────────────────────────────────────►│
       │  401 + WWW-Authenticate: Bearer ...                  │
       │     resource_metadata="…/.well-known/...protected…"  │
       │◄─────────────────────────────────────────────────────┤
       │  GET .well-known/oauth-protected-resource            │
       ├─────────────────────────────────────────────────────►│
       │  { authorization_servers: ["https://memo…"] }        │
       │◄─────────────────────────────────────────────────────┤
       │  GET .well-known/oauth-authorization-server          │
       ├─────────────────────────────────────────────────────►│
       │  { authorize, token, register, revoke URLs }         │
       │◄─────────────────────────────────────────────────────┤
       │  POST /oauth/register { client_name, redirect_uris } │
       ├─────────────────────────────────────────────────────►│
       │  201 { client_id: "mc_…", ... }                      │
       │◄─────────────────────────────────────────────────────┤
       │  → opens https://memo.../oauth/authorize?...         │
       │       (Clerk sign-in if not authed, then consent UI) │
       │  ← 303 redirect_uri?code=mac_…&state=…               │
       │  POST /oauth/token (grant=authorization_code,        │
       │       code, code_verifier, redirect_uri)             │
       ├─────────────────────────────────────────────────────►│
       │  200 { access_token: "ma_…",                         │
       │        refresh_token: "mr_…",                        │
       │        expires_in: 3600, ... }                       │
       │◄─────────────────────────────────────────────────────┤
       │  POST /api/mcp (Authorization: Bearer ma_…)          │
       │  → works                                             │
       │                                                      │
       │  (1h later)                                          │
       │  POST /oauth/token (grant=refresh_token)             │
       ├─────────────────────────────────────────────────────►│
       │  200 with NEW access_token + NEW refresh_token       │
       │  (old refresh_token marked rotated, single-use)      │
       │◄─────────────────────────────────────────────────────┤

What we deliberately don't support#

• The plain PKCE method. S256 only. PKCE-plain is essentially no protection at all for public clients.
• Implicit grant. Authorization Code + PKCE supersedes it for everything memo cares about.
• Confidential clients. All clients are public; PKCE is mandatory. We never issue or accept a client_secret — and the discovery doc advertises token_endpoint_auth_methods_supported: ["none"] so well-behaved clients won't ask for one.
• Long-lived access tokens. 1h hard cap. If you need persistent automation, mint a PAT instead.

Refresh-token rotation#

Every refresh exchange:

1. Loads the refresh-token row by sha256 of the raw value.
2. Verifies client_id match, no revoked_at, no rotated_at (single-use), and not expired.
3. Sets rotated_at = now() on the old row.
4. Mints a fresh access token + fresh refresh token via issueTokenPair.

If a client replays an already-rotated refresh token, we 400 with invalid_grant and the client must re-do the full authorize flow. This is the canonical defense against refresh-token theft.

Revocation cascades#

When an owner clicks Revoke on a connection at /u/<username>/settings/connections:

1. We set revoked_at on the targeted access token.
2. We also set revoked_at on every refresh token for the same (client_id, user_id) pair.

So a single revoke kills the entire connection — the client can't silently mint another access token even if it kept a stale refresh token.

Threat model summary#

See Security for the cross-cutting threat model.