Authentication
MemorySync accepts three authentication mechanisms: dashboard JWTs, API keys for server-to-server traffic, and OAuth 2.0 access tokens for third-party applications. All three resolve through the same auth middleware to a tenant + project + principal triple.
Mechanisms
| Mechanism | Header | Best for |
|---|---|---|
| JWT access token | Authorization: Bearer eyJ… | Dashboard, short-lived browser sessions. |
| API key | X-API-Key: ms_live_… (or as a Bearer) | Server-to-server, agent runtimes. |
| OAuth 2.0 access token | Authorization: Bearer … | Third-party apps acting on behalf of a user. |
JWT access & refresh
Login (POST /auth/login) returns an access token and a refresh token. Access tokens are short-lived; refresh tokens are long-lived and bound to the device. The dashboard rotates them automatically; if you sign requests by hand, call POST /auth/refresh with the refresh token before the access token expires.
API keys
Issued from /org/api-keys. Keys are scoped to one organisation and may be locked to a single project. They authorise both X-API-Key and Authorization: Bearer usage. Revocation is immediate — the auth middleware checks key state on every request.
OAuth 2.0 access tokens
Issued by the OAuth flow at POST /oauth/token. The access token carries granular scopes (memory:read, memory:write, summaries:read, …) which gate the routes the token can call.
Scopes & roles
- API keys are scoped to one organisation and optionally one project. Cross-project calls return
403 project_forbidden. - OAuth tokens carry granular scopes; the auth middleware rejects out-of-scope routes with
403 insufficient_scope. - Roles (
owner,admin,member,viewer) gate dashboard actions; admin endpoints additionally requireowneroradmin.
End-user resolution
Memory routes need an effective owner. JWT auth uses the JWT subject. API-key callers should pass X-End-User-ID when storing or recalling on behalf of an end user; without it, memories are filed under the API-key owner.
Revocation
- Revoke a JWT session at
DELETE /sessions/{session_id}. Effective immediately. - Revoke an API key from the dashboard or via
DELETE /org/api-keys/{key_id}. Effective immediately. - Revoke an OAuth token at
POST /oauth/revoke. Effective within one minute on every node.