API Auth Caller Model

This page answers one practical question: what auth should I send with this request?

Server-side callers

For backend services, workers, CLIs, and secure job runners, send your RetainDB API key.

Authorization: Bearer rdb_...

This is the expected model for most direct API usage.

Browser or dashboard callers

Do not embed a long-lived API key in client-side code.

Instead:

• authenticate the user to your own application
• resolve org, project, and user context on the server
• proxy the request or use a scoped backend flow

Which endpoints are usually server-side

These routes are typically called from trusted environments:

• POST /v1/memory
• POST /v1/memory/bulk
• POST /v1/memory/search
• POST /v1/context/query
• POST /v1/projects/:id/sources
• POST /v1/projects/:id/ingest

Minimal example

curl -X POST "https://api.retaindb.com/v1/memory/search" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "retaindb-quickstart",
    "user_id": "demo-alex",
    "query": "What should I know about this user?"
  }'

Common mistakes

Using a browser bundle with a raw API key

This is the most common auth mistake. Move the request to your server.

Mixing user identity with auth identity

user_id and session_id are request-scoping fields. They do not replace caller authentication.

Assuming the same pattern works for every environment

An SDK example running in Node is not permission to copy the same code into a browser component.

Next step

Go to memory search or projects and sources once your auth model is settled.