Auth Caller Model

Before you make a request, answer one question: where is this call happening?

That answer determines the auth model.

Use an API key for server-side calls

Use an API key when the request comes from:

• your backend
• a worker or job runner
• a server action
• a secure CLI or internal service
• MCP server processes running on trusted infrastructure

This is the default model for API and SDK integrations.

Authorization: Bearer rdb_...

Use the authenticated browser/dashboard model for user-facing app surfaces

Use the browser/dashboard model when the request is tied to an already authenticated user session in your web application. In that case, the browser is not where your long-lived key should live.

The safe pattern is:

1. browser authenticates to your app
2. your app resolves the user and org context
3. your backend makes the RetainDB request, or issues scoped credentials if your platform supports that pattern

The rule that prevents most mistakes

If you are unsure, default to a server-side API key flow. Most broken first integrations happen because people put a powerful key in the browser too early.

What to do next

• If you want to start from the server, continue to the 5 minute quickstart.
• If you want the formal request and header details, use the API reference at API auth caller model.
• If you are setting up browser or dashboard auth, resolve that before writing public client code.

Next step

Go to API auth caller model for the request-level reference.