JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Self-hosted dashboard and admin auth (#4837)

Browse Source 
Co-authored-by: kartik-mem0 <kartik.labhshetwar@mem0.ai>
This commit is contained in:
Gabriel Stein
2026-04-23 06:36:36 -07:00
committed by GitHub
parent 15feaa8ac4
commit db8ac61713
252 changed files with 20275 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/open-source/features/rest-api.mdx
+153 -45
View File
@@ -13,6 +13,10 @@ The Mem0 REST API server exposes every OSS memory operation over HTTP. Run it al
- You plan to explore or debug endpoints through the built-in OpenAPI page at `/docs`.
</Info>
<Warning>
**First time self-hosting, or upgrading from a pre-1.x build?** Start at [Self-Hosted Setup](/open-source/setup). It walks through the stack, the setup wizard, and the upgrade path for deployments that relied on open endpoints or `ADMIN_API_KEY`. This page covers the API surface and auth modes only.
</Warning>
<Warning>
**OSS vs Platform API paths:** The self-hosted OSS server does **not** use the `/v1/` prefix. For example, the endpoint is `POST /memories`, not `POST /v1/memories/`. The [API Reference](/api-reference) documents the hosted platform at `api.mem0.ai` which uses `/v1/` paths — those do not apply to the OSS server.
</Warning>
@@ -26,7 +30,7 @@ The Mem0 REST API server exposes every OSS memory operation over HTTP. Run it al
## Feature
- **CRUD endpoints:** Create, retrieve, search, update, delete, and reset memories by `user_id`, `agent_id`, or `run_id`.
- **API key authentication:** Optionally secure all endpoints with a shared API key via the `X-API-Key` header.
- **Authentication:** On by default. Dashboard sessions use JWTs; programmatic clients use per-user `X-API-Key` headers. Legacy `ADMIN_API_KEY` is still supported.
- **Status health check:** Access base routes to confirm the server is online.
- **OpenAPI explorer:** Visit `/docs` for interactive testing and schema reference.
@@ -40,51 +44,75 @@ The Mem0 REST API server exposes every OSS memory operation over HTTP. Run it al
<Tab title="Steps">
1. Create `server/.env` with your keys:
```bash
OPENAI_API_KEY=your-openai-api-key
```
```bash
OPENAI_API_KEY=your-openai-api-key
JWT_SECRET=$(openssl rand -base64 48)
```
2. Start the stack:
2. Bootstrap the stack in one command:
```bash
cd server
docker compose up
```
```bash
cd server
make bootstrap # starts Compose, creates an admin, issues the first API key
```
3. Reach the API at `http://localhost:8888`. Edits to the server or library auto-reload.
Or to start the stack only and finish setup via the browser wizard at http://localhost:3000:
```bash
cd server
docker compose up -d
```
3. API is at `http://localhost:8888`. Code edits auto-reload.
</Tab>
</Tabs>
### Run with Docker
<AccordionGroup>
<Accordion title="Other install paths">
**Run with Docker**
<Tabs>
<Tab title="Pull image">
<Tabs>
<Tab title="Pull image">
```bash
docker pull mem0/mem0-api-server
```
</Tab>
<Tab title="Build locally">
</Tab>
<Tab title="Build locally">
```bash
docker build -t mem0-api-server .
```
</Tab>
</Tabs>
</Tab>
</Tabs>
1. Create a `.env` file with `OPENAI_API_KEY`.
2. Run the container:
1. Create a `.env` file with `OPENAI_API_KEY` and `JWT_SECRET`.
2. Run the container:
```bash
docker run -p 8000:8000 --env-file .env mem0-api-server
```
```bash
docker run -p 8000:8000 --env-file .env mem0-api-server
```
3. Visit `http://localhost:8000`.
3. Visit `http://localhost:8000`.
### Run directly (no Docker)
**Run directly (no Docker)**
```bash
pip install -r requirements.txt
uvicorn main:app --reload
```
<Warning>
This path skips Docker and assumes Postgres is already running and reachable at `POSTGRES_HOST:POSTGRES_PORT`. For a single-command local setup with Postgres included, use Docker Compose above.
</Warning>
```bash
pip install -r requirements.txt
uvicorn main:app --reload
```
</Accordion>
</AccordionGroup>
<Note>
Compose publishes internal port 8000 as 8888 on the host. Raw Docker and raw uvicorn listen on 8000 unless remapped.
</Note>
<Note>
`JWT_SECRET` is required once auth is enabled — the server returns `500` on auth endpoints if it's unset. Generate one with `openssl rand -base64 48`. See [Self-Hosted Setup](/open-source/setup#configure-the-environment) for the full env var table.
</Note>
<Tip>
Use a process manager such as `systemd`, Supervisor, or PM2 when deploying the FastAPI server for production resilience.
@@ -98,35 +126,74 @@ uvicorn main:app --reload
## Authentication
The server supports optional API key authentication. When the `ADMIN_API_KEY` environment variable is set, every endpoint requires a valid `X-API-Key` header. The `/` redirect, `/docs`, and `/openapi.json` routes remain open so you can always reach the interactive API explorer.
Auth is on by default. Protected endpoints require either a JWT (from the dashboard login flow) or an `X-API-Key` header. The `/` redirect, `/docs`, and `/openapi.json` routes stay open so you can reach the OpenAPI explorer.
| `ADMIN_API_KEY` value | Behavior |
|---|---|
| Not set / empty | All endpoints are open (no auth) |
| Any non-empty string | Requests must include `X-API-Key: <your-key>` |
| Mode | How to send it | When to use it |
|---|---|---|
| Bearer JWT | `Authorization: Bearer <access_token>` | Dashboard sessions; tokens come from `POST /auth/login` and refresh via `POST /auth/refresh` |
| Per-user API key | `X-API-Key: m0sk_...` | Programmatic access scoped to a single dashboard user |
| Legacy `ADMIN_API_KEY` | `X-API-Key: <env value>` | Back-compat for deployments that set the `ADMIN_API_KEY` env var |
| `AUTH_DISABLED=true` | — | Local development only; bypasses auth entirely |
### Enable authentication
The `/docs` OpenAPI explorer supports both auth modes. Click **Authorize** at the top of the page and paste either `Bearer <access_token>` (JWT) or your `X-API-Key` value. Protected endpoints return `401` until you authorize.
Add the key to your `.env` file:
### Log in and use a JWT
Register the first admin (only works when no user exists yet), then log in:
```bash
ADMIN_API_KEY=your-secret-api-key
# First admin only — returns 403 after the first admin is registered
curl -X POST http://localhost:8888/auth/register \
-H "Content-Type: application/json" \
-d '{"name": "Admin", "email": "admin@example.com", "password": "strong-password"}'
```
Then include the header in every request:
```bash
curl -X POST http://localhost:8888/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@example.com", "password": "your-password"}'
```
Use the returned `access_token` as a bearer token:
```bash
curl -X POST http://localhost:8000/memories \
curl -X POST http://localhost:8888/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-api-key" \
-H "Authorization: Bearer <access_token>" \
-d '{
"messages": [{"role": "user", "content": "I love pizza."}],
"user_id": "alice"
}'
```
When the access token expires, exchange the refresh token at `POST /auth/refresh`.
### Create and use a per-user API key
Create a key from the dashboard **API Keys** page, or call `POST /api-keys` with a JWT. The full `m0sk_...` value is returned **once** at creation time — store it securely.
```bash
curl -X POST http://localhost:8888/memories \
-H "Content-Type: application/json" \
-H "X-API-Key: m0sk_your_key_here" \
-d '{
"messages": [{"role": "user", "content": "I love pizza."}],
"user_id": "alice"
}'
```
Per-user keys inherit the creating user's scope. List or revoke them via `GET /api-keys` and `DELETE /api-keys/{id}`.
### Legacy `ADMIN_API_KEY`
Set the `ADMIN_API_KEY` environment variable and send it as `X-API-Key`. The request is treated as admin-level and is not tied to a dashboard user. This mode is kept for back-compat with older self-hosted deployments — prefer JWT or per-user keys for new setups.
```bash
ADMIN_API_KEY=your-long-admin-key
```
<Warning>
The server logs a warning at startup when `ADMIN_API_KEY` is not set. Always set it in production.
Setting `AUTH_DISABLED=true` makes every protected endpoint open — the server logs a warning at startup when it's enabled. The server also warns when `ADMIN_API_KEY` is shorter than 16 characters. Never enable `AUTH_DISABLED` in production, and always use a long `ADMIN_API_KEY` if you rely on the legacy fallback.
</Warning>
---
@@ -136,7 +203,7 @@ curl -X POST http://localhost:8000/memories \
### Create and search memories via HTTP
```bash
curl -X POST http://localhost:8000/memories \
curl -X POST http://localhost:8888/memories \
-H "Content-Type: application/json" \
-d '{
"messages": [
@@ -151,7 +218,7 @@ curl -X POST http://localhost:8000/memories \
</Info>
```bash
curl -X POST http://localhost:8000/search \
curl -X POST http://localhost:8888/search \
-H "Content-Type: application/json" \
-d '{
"query": "vegetable",
@@ -161,7 +228,7 @@ curl -X POST http://localhost:8000/search \
### Explore with OpenAPI docs
1. Navigate to `http://localhost:8000/docs`.
1. Navigate to `http://localhost:8888/docs` (Compose) or `http://localhost:8000/docs` (raw Docker / uvicorn).
2. Pick an endpoint (e.g., `POST /search`).
3. Fill in parameters and click **Execute** to try requests in-browser.
@@ -175,9 +242,13 @@ curl -X POST http://localhost:8000/search \
The OSS REST server exposes the following endpoints. None use the `/v1/` prefix.
### Memory operations
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/configure` | Set memory configuration |
| `POST` | `/configure` | Set memory configuration. Rejects unbundled providers with a 400 |
| `GET` | `/configure` | Get the current memory configuration |
| `GET` | `/configure/providers` | List the LLM and embedder providers bundled in the container |
| `POST` | `/memories` | Create memories |
| `GET` | `/memories` | Get all memories (filter by `user_id`, `agent_id`, or `run_id`) |
| `GET` | `/memories/{memory_id}` | Get a specific memory |
@@ -188,6 +259,43 @@ The OSS REST server exposes the following endpoints. None use the `/v1/` prefix.
| `POST` | `/search` | Search memories |
| `POST` | `/reset` | Reset all memories |
### Authentication
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/auth/setup-status` | Returns `{needsSetup: bool}`. Open, no auth required |
| `POST` | `/auth/register` | Register the first admin. Registration closes after the first admin is created; additional accounts are provisioned by the existing admin. |
| `POST` | `/auth/login` | Exchange email and password for access and refresh JWTs |
| `POST` | `/auth/refresh` | Exchange a refresh token for a new access token |
| `GET` | `/auth/me` | Get the current authenticated user (JWT required) |
| `PATCH` | `/auth/me` | Update the caller's name or email. 409 if the new email is already in use |
| `POST` | `/auth/change-password` | Change the caller's password. 401 if the current password is wrong; new password must be at least 8 characters |
### API keys
All `/api-keys` endpoints require a JWT.
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api-keys` | List the caller's API keys |
| `POST` | `/api-keys` | Create a new key; the full `m0sk_...` value is returned once |
| `DELETE` | `/api-keys/{id}` | Revoke an API key |
### Request logs
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/requests?limit=N` | Recent API call log (JWT or admin key) |
### Entities
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/entities` | Distinct `user_id` / `agent_id` / `run_id` values with memory counts |
| `DELETE` | `/entities/{entity_type}/{entity_id}` | Cascade-delete all memories for an entity; `entity_type` is `user`, `agent`, or `run` |
The `/auth/*`, `/api-keys`, `/requests`, and `/entities` routes are new to the self-hosted server and primarily back the dashboard, but you can call them directly from your own tooling.
---
## Verify the feature is working
@@ -201,7 +309,7 @@ The OSS REST server exposes the following endpoints. None use the `/v1/` prefix.
## Best practices
1. **Enable authentication:** Set `ADMIN_API_KEY` to secure all endpoints, or use an API gateway for more advanced schemes.
1. **Keep auth on:** Auth is enabled by default. Never set `AUTH_DISABLED=true` in production. If you rely on `ADMIN_API_KEY`, use a long value (16+ chars) or prefer per-user API keys.
2. **Use HTTPS:** Terminate TLS at your load balancer or reverse proxy.
3. **Monitor uptime:** Track request rates, latency, and error codes per endpoint.
4. **Version configs:** Keep environment files and Docker Compose definitions in source control.