Authentication

SharedMemory exposes two UX layers for signing in humans — then every SDK, MCP server, CLI command, or custom script authenticates programmatically via Bearer secrets that begin with sm_.

Bearer API keys (sm_…)

All SDK/MCP integrations send:

Authorization: Bearer sm_org_rw_xxxx...

ensureAuth, ensureAgentAuth, MCP, and connectors accept any valid hashed secret tied to your workspace.

Prefer Settings → API Keys

1. Sign in at app.sharedmemory.ai
2. Navigate to Settings → API Keys
3. Create a descriptive key and copy it immediately (shown once)

These keys unlock org-wide or single-project workloads:

Prefix	Scope	Typical use
sm_org_rw_	Org (read/write)	Automations spanning multiple projects
sm_org_r_	Org (read-only)	Dashboards / analytics ingest
sm_proj_rw_	Single project (volume_id)	Agent + IDE integrations scoped to one product
sm_proj_r_	Single project read-only	Log shipping / auditors

MCP + Dashboard Setup snippets

Dashboard Setup copies the same bearer format for MCP (SHAREDMEMORY_API_KEY) and REST examples. Prefer org/project keys so you can revoke them independently of agent profiles.

Agent profiles (POST /agents)

Creating an agent profile issues a sm_agent_… key stored exactly like dashboard keys (api_keys table + optional link to agent metadata).

sm login CLI flow

Running sm login exchanges a browser OAuth session for a fresh sm_live_… key written to CLI config (name = "CLI" in api_keys). Treat it exactly like every other bearer secret — rotate periodically.

Rotate if leaked

Secrets are hashed with SHA‑256 server-side after first display. Rotate by revoking/regenerating the key in Dashboard or sm agents … rotate-key for agent keys.

Session authentication (web dashboard only)

Humans authenticate to the SPA with Passport.js-backed sessions (httpOnly cookie). This path never replaces bearer keys — it scopes the docs UI/API requests you make while browsing.

Supported methods:

• Email + password
• Google OAuth

Agent-volume permissions (/agent/connect)

/agent/connect binds an sm_agent_… key to specific volumes (read, write, etc.). Scoped org/project keys still enforce PostgreSQL-backed checks via ensureAgentVolumeAccess.

Rate Limits

Endpoint family	Typical limit
POST /agent/memory/write	30 requests · 1 minute
POST /agent/memory/query	60 requests · 1 minute
POST /memory/propose, /memory/query, /memory/search	Plan-gated quotas + enforceKeyRateLimit
POST /agent/documents/upload	50 uploads · 1 hour
/auth/* (login/signup/email)	20 requests · 15 minutes

Rate limit headers: X-RateLimit-*.

Common errors

Status	Error slug	Meaning
401	unauthorized, invalid_api_key	Missing or unknown bearer secret
403	agent_not_authorized_for_volume	Scoped key cannot access requested volume_id
429	rate_limited	Plan or per-key throughput exceeded

See also: Dashboard overview and API Overview for canonical endpoint paths.