Skip to main content

​
Authentication

MEMANTO uses a two-header authentication system: Moorcheh API key for all requests, and session tokens for memory operations.

​
API Key Authentication

​
Required Header

Every request to MEMANTO API must include: 
Authorization: Bearer mk_your_api_key_here

​
Getting Your API Key

  1. Go to https://console.moorcheh.ai/api-keys
  2. Create a new API key
  3. Copy the key (starts with mk_)
  4. Use in Authorization header

​
Example Request

curl -X GET "http://localhost:8000/api/v2/agents" \
  -H "Authorization: Bearer mk_your_api_key"

​
In Python

import httpx

api_key = "mk_your_api_key"
headers = {"Authorization": f"Bearer {api_key}"}

response = httpx.get(
    "http://localhost:8000/api/v2/agents",
    headers=headers
)

​
Session Token Authentication

​
When Session Tokens Are Required

Memory operations require a session token from agent activation:
  • POST /agents/{agent_id}/remember
  • GET /agents/{agent_id}/recall
  • POST /agents/{agent_id}/answer
  • All temporal queries
  • All memory management endpoints

​
Getting a Session Token

  1. Activate an agent:
curl -X POST "http://localhost:8000/api/v2/agents/my-agent/activate" \
  -H "Authorization: Bearer mk_your_api_key"
  1. Response contains session token:
{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_id": "my-agent",
  "expires_at": "2025-03-31T22:30:00Z"
}
  1. Use 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 "Authorization: Bearer mk_your_api_key" \
  -H "X-Session-Token: eyJhbGc..." \
  -d '{"content": "Hello", "type": "fact"}'

​
In Python

import httpx

api_key = "mk_your_api_key"

# 1. Activate to get session token
activate_resp = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
session_token = activate_resp.json()["session_token"]

# 2. Use session token for memory operations
headers = {
    "Authorization": f"Bearer {api_key}",
    "X-Session-Token": session_token
}

remember_resp = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/remember",
    params={"content": "Hello", "type": "fact"},
    headers=headers
)

​
Endpoints Not Requiring Session Token

These endpoints only need API key:
  • POST /agents - Create agent
  • GET /agents - List agents
  • GET /agents/{agent_id} - Get agent details
  • DELETE /agents/{agent_id} - Delete agent
  • POST /agents/{agent_id}/activate - Activate (returns token)
  • POST /agents/{agent_id}/deactivate - Deactivate
  • GET /session/current - Check session (needs token)

​
Session Token Details

​
Token Format

Session tokens are JWT (JSON Web Tokens): 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJhZ2VudF9pZCI6Im15LWFnZW50IiwiZXhwaXJlc19hdCI6IjIwMjUtMDMtMzFUMjI6MzA6MDBaIn0.
[signature]

​
Token Expiration

  • Duration: 6 hours from activation
  • Checking expiry: Decode token to see expires_at
  • Extending: Use POST /session/extend
  • Renewal: Activate new session

​
Decode Token (Python)

import jwt

token = "eyJhbGc..."

payload = jwt.decode(
    token,
    options={"verify_signature": False}  # Don't verify signature
)

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

​
Error: Invalid API Key

​
Symptom

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or expired"
  }
}

​
Solutions

  1. Check API key format (should start with mk_)
  2. Verify key hasn’t been rotated in Moorcheh Console
  3. Ensure no typos in header value
  4. Generate new key if needed

​
Error: Missing Session Token

​
Symptom

{
  "status": "error",
  "error": {
    "code": "MISSING_SESSION_TOKEN",
    "message": "X-Session-Token header is required"
  }
}

​
Solutions

  1. Activate agent first: POST /agents/{agent_id}/activate
  2. Save the returned session_token
  3. Include token in X-Session-Token header

​
Error: Expired Session Token

​
Symptom

{
  "status": "error",
  "error": {
    "code": "EXPIRED_SESSION_TOKEN",
    "message": "Session token has expired"
  }
}

​
Solutions

  1. Extend existing session: POST /session/extend
  2. Or activate new session: POST /agents/{agent_id}/activate

​
Best Practices

​
DO

  • Store API key in environment variable
  • Use secrets manager for production
  • Keep session tokens in memory (don’t persist)
  • Extend sessions before expiry
  • Rotate API keys periodically

​
DON’T

  • Commit API keys to git
  • Hardcode keys in code
  • Share API keys
  • Use same key across environments
  • Log tokens to files

​
Security

​
API Key Management

Development: 
export MOORCHEH_API_KEY=mk_dev_key
Production (AWS Secrets Manager): 
import boto3

client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='memanto/api-key')
api_key = secret['SecretString']
Production (Environment): 
# In deployment platform
MOORCHEH_API_KEY=mk_prod_key

​
Session Token Security

  • Tokens are JWT - treat as sensitive
  • Don’t log tokens
  • Don’t expose in client code
  • Short-lived (6 hours)
  • Unique per activation

​
Authentication Flow Diagram

┌─────────────┐
│   Your App  │
└──────┬──────┘
       │
       ├─ All Requests ──────────────────┐
       │                                  │
       │ Authorization: Bearer mk_key    ▼
       │                          ┌──────────────┐
       │                          │ MEMANTO API  │
       │                          └──────────────┘
       │
       └─ Memory Operations ──────────────┐
                                          │
           X-Session-Token: jwt          ▼

​
Next Steps