Authentication
Authenticate RetainDB dashboard, API, MCP, and SDK flows safely.
Applies to: RetainDB API v1
RetainDB has two auth models:
- Dashboard session auth for humans using RetainDB Cloud.
- API key auth for servers, MCP agents, SDKs, workers, CLIs, and external automation.
Normal dashboard users should not create or handle API keys.
API Key Auth
Send your key from server-side code:
http
Authorization: Bearer rdb_...Alternative header:
http
X-API-Key: rdb_...Recommended environment variables:
bash
RETAINDB_API_KEY="rdb_..."
RETAINDB_API_URL="https://api.retaindb.com"
RETAINDB_PROJECT="production"Dashboard Session Auth
Dashboard source and query flows use the logged-in user's session. The dashboard validates organization and project membership, then calls RetainDB server-side.
That means:
- users can connect sources and ask the company brain without an API key
- browser code does not receive RetainDB API keys
- API keys stay under Developers for external agents and servers
Caller Scope
RetainDB does not guess your app's identity model. Your server should authenticate the caller, then attach stable scope fields:
| Field | Use it for |
|---|---|
project | product, environment, workspace, or customer namespace |
user_id | app user memory |
session_id | conversation or workflow memory |
agent_id | agent actor |
task_id | shared agent task |
Safe Defaults
- Keep API keys out of browser JavaScript.
- Use separate keys for development, staging, and production.
- Rotate keys pasted into logs, screenshots, chats, or public tickets.
- Scope keys narrowly when your deployment supports scopes.
- Log
trace_id, not full secrets or full context payloads.
Common Mistakes
| Symptom | Cause | Fix |
|---|---|---|
| 401 from MCP | key missing in MCP env | add RETAINDB_API_KEY and restart host |
| dashboard works but API fails | dashboard session is not an API key | create a key under Developers |
| API works locally but not Vercel | env var missing in deployment | add server-side env vars and redeploy |
| user sees another user's memory | unstable or wrong user_id | set scope after your own auth check |
Next: Connect Agents, Memory API, or Company Brain API.
Was this page useful?
Your feedback helps us make the product easier to ship with.