Authentication

SharedMemory uses two authentication methods depending on the context.

Agent API Keys (for programmatic access)

All SDK, CLI, MCP, and direct API calls authenticate using Bearer tokens.

Authorization: Bearer sm_agent_abc123...

Getting an API key

1. Sign in to the dashboard
2. Go to Settings → Agents
3. Click Register Agent — provide a name and optional description
4. Copy the API key (sm_agent_...)

warning

API keys are shown once at creation time. Store it securely. If lost, delete the agent and create a new one.

Key format

Prefix	Purpose
sm_live_	User API key (browser extension, session)
sm_agent_	Agent API key
sm_proj_rw_	Project-scoped read/write key
sm_proj_r_	Project-scoped read-only key
sm_org_rw_	Org-scoped read/write key
sm_org_r_	Org-scoped read-only key

Keys are hashed (SHA-256) before storage. SharedMemory never stores raw API keys.

Agent-volume permissions

An agent must be connected to a volume before it can read or write:

POST /agent/connect
{
  "agent_id": "agent-uuid",
  "volume_id": "volume-uuid",
  "permissions": ["read", "write"]
}

Session Authentication (for dashboard)

The web dashboard uses session cookies with Passport.js:

• Email/Password — Standard local auth with bcrypt hashing
• Google OAuth — One-click sign-in via Google

Rate Limits

Endpoint	Limit	Window
POST /agent/memory/write	30 requests	1 minute
POST /agent/memory/query	60 requests	1 minute
POST /agent/documents/upload	50 requests	1 hour
Auth endpoints (/login, /signup)	20 requests	15 minutes

Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Responses

Status	Error	Meaning
401	unauthorized	Missing or invalid API key
403	agent_not_authorized_for_volume	Agent not connected to this volume
429	rate_limited	Too many requests