Skip to main content

​
Authentication

Memanto uses a server-side Moorcheh API key combined with per-agent session tokens to scope memory operations. API clients do not send an Authorization header — the Moorcheh key is configured on the Memanto server (via MOORCHEH_API_KEY) and validated at startup.

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

  1. Go to https://console.moorcheh.ai/api-keys
  2. Create a new API key
  3. 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
  • POST /api/v2/agents/{agent_id}/upload-file
  • 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
  • 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.

​
Endpoints That Do Not Require a Session Token

These endpoints only need the server to be running (no client-side credentials):
  • 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)
  • GET /api/v2/status — Inspect the active session

​
Getting a Session Token

  1. Activate an agent:
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate"
  1. 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"
}
  1. 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.
  • Renewal: activate a new session with POST /api/v2/agents/{agent_id}/activate.

​
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.

​
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

​
DON’T

  • Commit MOORCHEH_API_KEY to source control
  • Send the Moorcheh key from clients (Memanto does not read it from request headers)
  • Reuse a session token across different agents
  • Log session tokens to files or telemetry

​
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