Authentication & Multi-Tenancy
SmartMemory's hosted API enforces tenant isolation at the security layer (the
SecureSmartMemory wrapper), not in route handlers. Every request resolves to
a MemoryScopeProvider that auto-injects scope metadata on writes and
auto-filters on reads.
Required headers
| Header | Required | Purpose |
|---|---|---|
Authorization | All authenticated routes | Bearer <jwt> (Clerk-issued or refresh-rotated) |
X-Workspace-Id (alias X-Team-Id) | Most routes — workspace context | Selects the workspace data boundary |
X-API-Key | API-key mode only | Replaces Authorization for server-to-server |
The active workspace is required by every route whose ScopePolicy is
team_required (most write paths and ingestion). Routes with
ScopePolicy.user_only work for any authenticated user without a workspace.
Isolation levels
service_common.security.scope_provider.IsolationLevel defines three modes:
| Level | Reads see | Writes are tagged with |
|---|---|---|
WORKSPACE (default) | Workspace data + the caller's personal items | workspace_id + tenant_id + user_id |
USER | Only the caller's items within the workspace | workspace_id + user_id |
TENANT | Every workspace in the tenant | tenant_id |
Source: smart-memory-common/service_common/security/scope_provider.py. The
default is intentionally permissive — the whole point of a workspace is shared
collaboration. Drop to USER for personal-data-only workloads, raise to
TENANT for organisation-wide admin tooling.
Auth flow — Clerk JWT
The hosted control plane uses Clerk for identity. The web SDK exchanges a Clerk session for a SmartMemory access + refresh token pair:
Clerk login POST /auth/clerk/session
│ (body: { clerk_token })
▼ ──────────────────────►
client (browser) ──────► SmartMemory API
▲ ◄──────────────────────
│ sets sm_access_token / sm_refresh_token
│ cookies (or returns JSON for SDK)Tokens are short-lived. The JS SDK's RefreshManager rotates them silently via
POST /auth/refresh before expiry; on cookie auth, the body is empty and the
refresh token is read from sm_refresh_token.
Manual flow:
curl -X POST https://api.smartmemory.ai/auth/clerk/session \
-H 'content-type: application/json' \
-d '{"clerk_token": "<clerk_jwt>"}'
# → { "access_token": "...", "refresh_token": "...", "user": {...} }
# Inspect the active session
curl https://api.smartmemory.ai/auth/me \
-H 'authorization: Bearer <access_token>'
# Refresh
curl -X POST https://api.smartmemory.ai/auth/refresh \
-H 'content-type: application/json' \
-d '{"refresh_token": "..."}'
# Logout (this device)
curl -X POST https://api.smartmemory.ai/auth/logout \
-H 'authorization: Bearer <access_token>'
# Logout (all devices)
curl -X POST https://api.smartmemory.ai/auth/logout-all \
-H 'authorization: Bearer <access_token>'/auth/onboarding/{start,complete,retry} drives the post-signup workspace
provisioning sequence — usually called by the web UI after Clerk signup.
Auth flow — API keys
For server-to-server callers, mint a key under the user's account:
# Create
curl -X POST https://api.smartmemory.ai/memory/api-keys \
-H 'authorization: Bearer <access_token>' \
-H 'content-type: application/json' \
-d '{
"name": "ingestion-bot",
"scopes": ["read:memories", "write:memories"],
"expires_in_days": 90
}'
# → { "id": "...", "key_prefix": "...", "key": "sm_live_..." }
# The full key is only shown once. Minted keys are prefixed `sm_live_`
# (production) or `sm_test_` (test environment).
# List
curl https://api.smartmemory.ai/memory/api-keys -H 'authorization: Bearer <token>'
# Revoke
curl -X DELETE https://api.smartmemory.ai/memory/api-keys/<key_id> \
-H 'authorization: Bearer <token>'Use the key as either Authorization: Bearer <key> or X-API-Key: <key>.
Keys with the write:telemetry scope must be bound to a workspace
(team_id in the create body).
Managing keys needs a signed-in user session (a JWT), not an API key. A request
made with an API key to create, list or revoke keys, or to delete an agent
(which revokes the agent's keys), returns 403. In the SDKs this covers Python
create_api_key, list_api_keys, revoke_api_key and delete_agent, and the
JS AuthAPI api-keys calls, so run them from a client signed in as the user.
A key bound to a workspace also cannot create teams, workspaces or agents.
Common patterns
Per-user memory inside a workspace
Create the MemoryScopeProvider with IsolationLevel.USER. Reads and writes
are scoped to (workspace_id, user_id). Useful for personal scratchpads in a
shared product.
from service_common.security.scope_provider import (
MemoryScopeProvider,
IsolationLevel,
)
scope = MemoryScopeProvider(
user_id=user.id,
tenant_id=user.tenant_id,
workspace_id=team.id,
isolation_level=IsolationLevel.USER,
)Team-shared memory (default)
IsolationLevel.WORKSPACE is the default. All users in the workspace see
shared items, plus their own personal items. This is the right choice for
99% of multi-user products.
Key API routes
/auth/*: Clerk session exchange, token refresh, current user, and logout (POST /auth/clerk/session,POST /auth/refresh,GET /auth/me,POST /auth/logout)/memory/api-keys: create, list, and delete API keys
See also
- JavaScript SDK —
mode: 'apiKey' | 'clerk' | 'sso'