Authentication

Memanto uses a server-side Moorcheh API key combined with per-agent session tokens to scope memory operations, plus a separate management credential that gates agent lifecycle endpoints (create/list/get/delete/activate/deactivate an agent, and the status endpoint).

Server (Moorcheh)

Memanto reads MOORCHEH_API_KEY from its environment / configuration and authenticates on the server when calling Moorcheh.

export MOORCHEH_API_KEY=your_moorcheh_key

Memory Operations (Client)

Memory endpoints require a session token in the X-Session-Token header. Tokens are obtained by activating an agent.

X-Session-Token: your_jwt_token

Server-Side Moorcheh API Key

Memanto does not accept a Moorcheh API key from clients. The key is set once on the server and is used for every Moorcheh call Memanto makes:

# Required on the Memanto server
export MOORCHEH_API_KEY=your_moorcheh_key

If the key is missing or invalid, Memanto fails fast at startup with MOORCHEH_API_KEY is not configured or MOORCHEH_API_KEY is invalid.

Getting a Moorcheh API Key

Go to https://console.moorcheh.ai/api-keys
Create a new API key
Configure it on the Memanto server (env var, secrets manager, etc.)

Session Token Authentication

When Session Tokens Are Required

Memory operations require an X-Session-Token header obtained from agent activation:

POST /api/v2/agents/{agent_id}/remember
POST /api/v2/agents/{agent_id}/batch-remember
PATCH /api/v2/agents/{agent_id}/memories/{memory_id}
POST /api/v2/agents/{agent_id}/remember/extract
POST /api/v2/agents/{agent_id}/upload-file
DELETE /api/v2/agents/{agent_id}/memories/{memory_id}
POST /api/v2/agents/{agent_id}/recall
POST /api/v2/agents/{agent_id}/recall/as-of
POST /api/v2/agents/{agent_id}/recall/changed-since
POST /api/v2/agents/{agent_id}/recall/recent
POST /api/v2/agents/{agent_id}/answer
POST /api/v2/agents/{agent_id}/daily-summary
POST /api/v2/agents/{agent_id}/conflicts/generate
GET /api/v2/agents/{agent_id}/conflicts
POST /api/v2/agents/{agent_id}/conflicts/resolve
POST /api/v2/agents/{agent_id}/deactivate

The session must match agent_id in the path; otherwise the request is rejected. As an alternative to the X-Session-Token header, Activate Agent also sets an HttpOnly, SameSite=Strict cookie named memanto_session_token. get_current_session accepts either the header or the cookie — browser clients (like the built-in Web UI) never need to read the token out of JavaScript.

The cookie is set on POST /api/v2/agents/{agent_id}/activate and cleared on POST /api/v2/agents/{agent_id}/deactivate.
The cookie’s Secure attribute is set dynamically from the actual request scheme (Secure when the request arrived over HTTPS, omitted over plain HTTP). Memanto binds 0.0.0.0 with no built-in TLS by default, so a hardcoded Secure flag would silently stop browsers from ever sending the cookie back in that default deployment — put Memanto behind an HTTPS-terminating proxy in production to get Secure cookies.
If a near-expiry session is auto-renewed mid-request, the server transparently re-sets the cookie with the new token so cookie-authenticated clients don’t go stale.
API clients that use the X-Session-Token header (CLI, SDKs, direct API integrations) are unaffected — the cookie is purely additive for browser-based callers.

Management Endpoint Authentication (Agent Lifecycle)

Agent-lifecycle endpoints don’t take a session token (there’s no session yet), but as of v0.2.7 they do require authorization — either a management credential or a loopback client:

POST /api/v2/agents — Create agent
GET /api/v2/agents — List agents
GET /api/v2/agents/{agent_id} — Get agent details
DELETE /api/v2/agents/{agent_id} — Delete agent
POST /api/v2/agents/{agent_id}/activate — Activate (returns the token)
POST /api/v2/agents/{agent_id}/deactivate — Deactivate (also checked here, in addition to the session token above)
GET /api/v2/status — Inspect the active session

Prior to v0.2.7, these endpoints only checked that the server had a configured MOORCHEH_API_KEY — not that the caller was authorized. Combined with the default HOST=0.0.0.0 bind, any network peer could create agents, activate sessions, and obtain session tokens. Upgrade if you’re running an older version and Memanto is reachable from outside localhost.

Access is granted when either of these is true:

The caller presents the management credential, matched with a constant-time comparison against the configured server credential:
Authorization: Bearer <key>
or
X-Api-Key: <key>
The expected credential is MOORCHEH_API_KEY on the cloud backend, or MEMANTO_SECRET_KEY on the on-prem backend (see Session cookie hardening for how that same secret is generated when unset).
The request is a genuine loopback request — so the local desktop CLI and Web UI keep working without attaching a key on every call. All three of these must hold:
- the client address is loopback (127.0.0.1 / ::1, including IPv4-mapped IPv6);
- the Host header also names loopback (localhost or a loopback IP);
- the request is not a cross-site browser request — if an Origin header is present it must itself be a loopback origin, and otherwise Sec-Fetch-Site must not be cross-site or same-site.
The last two conditions are newer than the loopback check itself. A local client that sends a non-loopback Host — most commonly a reverse proxy that forwards Host: memanto.example.com to a loopback-bound Memanto — no longer inherits loopback trust and now gets a 401. Attach the management credential on those calls, or make the proxy forward a loopback Host.The Origin / Sec-Fetch-Site conditions close a CSRF hole: without them, any web page the operator visited could drive agent-lifecycle endpoints on localhost from the browser and read back a session token. Ordinary non-browser callers (curl, the CLI, server-side SDKs) send neither header and are unaffected.

Requests that satisfy neither condition get:

401 - Unauthorized (Management Auth Required)

{
  "detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer <key> or X-Api-Key)."
}

Endpoints that remain fully open (no management credential, no loopback requirement):

GET /health, GET /ready, GET /live — Health & Readiness probes

Getting a Session Token

Activate an agent (from localhost, no management credential needed):

curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate"

From a non-loopback host, attach the management credential:

curl -X POST "https://memanto.example.com/api/v2/agents/my-agent/activate" \
  -H "Authorization: Bearer $MOORCHEH_API_KEY"

Response contains a session token:

{
  "session_id": "9f733fdb-ebf2-494e-8eb6-fb3320d6020d",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_id": "my-agent",
  "namespace": "memanto_agent_my-agent",
  "started_at": "2026-05-09T02:40:00Z",
  "expires_at": "2026-05-09T08:40:00Z",
  "pattern": "support",
  "status": "active"
}

Use the token in subsequent requests:

X-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Request with Session Token

curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember" \
  -H "X-Session-Token: eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "type": "fact"}'

In Python

import httpx

base_url = "http://localhost:8000"

# 1. Activate to get a session token
activate_resp = httpx.post(f"{base_url}/api/v2/agents/my-agent/activate")
session_token = activate_resp.json()["session_token"]

# 2. Use the session token for memory operations
headers = {
    "X-Session-Token": session_token,
    "Content-Type": "application/json",
}

remember_resp = httpx.post(
    f"{base_url}/api/v2/agents/my-agent/remember",
    headers=headers,
    json={"content": "Hello", "type": "fact"},
)

Session Token Details

Token Format

Session tokens are JWT (JSON Web Tokens):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJhZ2VudF9pZCI6Im15LWFnZW50IiwiZXhwaXJlc19hdCI6IjIwMjYtMDUtMDlUMDg6NDA6MDBaIn0.
[signature]

Token Expiration

Duration: configured by the server via SESSION_DEFAULT_DURATION_HOURS (typically 6 hours).
Auto-renewal: Memanto auto-renews sessions that are near expiry on the next memory request. A renewed session gets a new token, which invalidates the one you sent — see below for how to pick it up.
Auto-recreation: if a session has already fully expired, Memanto issues a brand-new session on the next request instead of failing with 401, provided the caller clears the same management-access check as explicit activation. Controlled by SESSION_AUTO_RECREATE_ENABLED (default True). The replacement token is handed back exactly like a renewal.
Renewal: activate a new session with POST /api/v2/agents/{agent_id}/activate.

When a session is auto-renewed or auto-recreated, the response carries the new token in an X-Session-Token response header. Header-authenticated clients must read that header and use the new value on subsequent requests — the token you originally sent is no longer valid. (Cookie-authenticated browser clients are handled automatically; the server re-sets the cookie.) The header is listed in the CORS expose_headers allowlist, so browser JavaScript can read it cross-origin.

Decode Token (Python)

import jwt

token = "eyJhbGc..."
payload = jwt.decode(token, options={"verify_signature": False})

print(f"Agent: {payload['agent_id']}")
print(f"Expires: {payload['expires_at']}")

Common Errors

Missing Session Token

{
  "detail": "Missing session token. Use X-Session-Token header."
}

Fix: Activate the agent and include the returned token in X-Session-Token.

Invalid Session Token

{
  "detail": {
    "error": "InvalidSessionToken",
    "message": "Invalid session token: Not enough segments",
    "details": {}
  }
}

Fix: Re-activate the agent and use the freshly returned token.

Session Expired

{
  "detail": {
    "error": "SessionExpired",
    "message": "Session has expired",
    "details": {}
  }
}

Fix: Activate a new session with POST /api/v2/agents/{agent_id}/activate.

With SESSION_AUTO_RECREATE_ENABLED on (the default), you will only see this error when auto-recreation does not apply: the caller failed the management-access check (a remote request with no management credential), the session was explicitly ended via POST /api/v2/agents/{agent_id}/deactivate, or a newer session already superseded the token you sent. Sessions that were deliberately deactivated are never resurrected — activate explicitly after logout.

Management Auth Required

{
  "detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer <key> or X-Api-Key)."
}

Fix: Attach Authorization: Bearer <key> or X-Api-Key: <key> (the cloud MOORCHEH_API_KEY or the on-prem MEMANTO_SECRET_KEY), or call from a loopback client. See Management Endpoint Authentication.

Session / Agent Mismatch

If the session token was issued for a different agent than the one in the URL path, the server returns 500 with:

{
  "detail": {
    "error": "InternalServerError",
    "message": "An unexpected error occurred",
    "details": {
      "original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
    }
  }
}

Fix: Activate the correct agent or call the endpoint with the matching agent_id.

Best Practices

DO

Store MOORCHEH_API_KEY as a server-side secret (env var, Secrets Manager, etc.)
Keep session tokens in memory on the client (don’t persist long-term)
Rotate the Moorcheh key periodically
Treat session tokens as sensitive — they grant memory access for an agent
If Memanto is reachable from outside localhost, attach Authorization: Bearer <key> or X-Api-Key on agent-lifecycle calls — don’t rely on network placement alone

DON’T

Commit MOORCHEH_API_KEY to source control
Reuse a session token across different agents
Log session tokens (or the management credential) to files or telemetry
Bind Memanto to 0.0.0.0 on an untrusted network without also setting a real MOORCHEH_API_KEY / MEMANTO_SECRET_KEY — that credential is what gates agent-lifecycle access for non-loopback callers

Security

API Key Management

Development:

export MOORCHEH_API_KEY=dev_key

Production (AWS Secrets Manager):

import boto3

client = boto3.client("secretsmanager")
secret = client.get_secret_value(SecretId="moorcheh/api-key")
api_key = secret["SecretString"]

Production (Environment):

# In your deployment platform
MOORCHEH_API_KEY=prod_key

Session Token Security

Tokens are JWT — treat as sensitive
Don’t log tokens
Don’t expose in client-side code that ships to end users
Short-lived (configurable, default ~6 hours)
Unique per activation

Next Steps

Activate Agent to obtain a session token
Get Current Session to inspect the active session
Remember to start storing memories

Getting Started

System

Agent Management

Session Management

Data

Expiry Policy

Search & Discovery

AI Generation

Authentication

Authentication

Server (Moorcheh)

Memory Operations (Client)

Server-Side Moorcheh API Key

Getting a Moorcheh API Key

Session Token Authentication

When Session Tokens Are Required

Management Endpoint Authentication (Agent Lifecycle)

Getting a Session Token

Example Request with Session Token

In Python

Session Token Details

Token Format

Token Expiration

Decode Token (Python)

Common Errors

Missing Session Token

Invalid Session Token

Session Expired

Management Auth Required

Session / Agent Mismatch

Best Practices

DO

DON’T

Security

API Key Management

Session Token Security

Next Steps

​Authentication

Server (Moorcheh)

Memory Operations (Client)

​Server-Side Moorcheh API Key

​Getting a Moorcheh API Key

​Session Token Authentication

​When Session Tokens Are Required

​Cookie-Based Authentication (Browser / Web UI Clients)

​Management Endpoint Authentication (Agent Lifecycle)

​Getting a Session Token

​Example Request with Session Token

​In Python

​Session Token Details

​Token Format

​Token Expiration

​Decode Token (Python)

​Common Errors

​Missing Session Token

​Invalid Session Token

​Session Expired

​Management Auth Required

​Session / Agent Mismatch

​Best Practices

​ DO

​ DON’T

​Security

​API Key Management

​Session Token Security

​Next Steps

Authentication

Server-Side Moorcheh API Key

Getting a Moorcheh API Key

Session Token Authentication

When Session Tokens Are Required

Cookie-Based Authentication (Browser / Web UI Clients)

Management Endpoint Authentication (Agent Lifecycle)

Getting a Session Token

Example Request with Session Token

In Python

Session Token Details

Token Format

Token Expiration

Decode Token (Python)

Common Errors

Missing Session Token

Invalid Session Token

Session Expired

Management Auth Required

Session / Agent Mismatch

Best Practices

DO

DON’T

Security

API Key Management

Session Token Security

Next Steps