Skip to main content

​
Authentication

MemSync uses simple API key authentication to protect user data and ensure only authorized access to memories and profiles.
Coming Soon: OAuth 2.0 authentication will be available for enhanced security and easier integration with third-party applications.

​
API Key Authentication

​
How it Works

MemSync uses API keys for authentication:
1

API Key Generation

Generate an API key from your MemSync dashboard
2

API Requests

Include the API key in the X-API-Key header for all API requests
3

Key Validation

MemSync validates the API key and permissions

​
Using API Keys

import requests

# Include API key in all API requests
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Example API call
response = requests.post("https://api.memchat.io/v1/memories/search",
    headers=headers,
    json={"query": "user interests", "limit": 5}
)

​
Key Requirements

  • Header: X-API-Key
  • Validation: Must be a valid, active API key
  • Format: Simple string key

​
API Key Features

Simple Integration

Easy integration for third-party applications and services

Enhanced Security

App-specific keys with granular permissions and rate limiting

Usage Tracking

Monitor API usage and performance

Easy Management

Create and manage keys through the dashboard

​
Security Best Practices

​
API Key Security

Store API keys securely and never expose them in client-side code
# ✅ Good: Store in environment variables
import os
API_KEY = os.environ.get("MEMSYNC_API_KEY")

# ❌ Bad: Hardcode in source code
API_KEY = "your_api_key_here"  # Never do this!
Keep your API keys secure and rotate them when needed
def make_authenticated_request(endpoint, data):
    headers = {"X-API-Key": API_KEY}
    
    try:
        response = requests.post(endpoint, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            # Handle invalid API key
            raise AuthenticationError("Invalid API key")
        raise
Handle authentication errors gracefully
def make_authenticated_request(endpoint, data):
    headers = {"X-API-Key": API_KEY}
    
    try:
        response = requests.post(endpoint, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            # Handle invalid API key
            raise AuthenticationError("Invalid API key")
        raise

​
Network Security

  • HTTPS Only: All API communications use HTTPS encryption
  • Rate Limiting: Built-in rate limiting prevents abuse
  • Request Validation: All requests are validated for proper format and permissions

​
User Context

MemSync automatically associates API requests with your account: 
# The API key is associated with your account
# MemSync automatically handles:
# - User identification
# - Data isolation
# - Access permissions

response = requests.post("https://api.memchat.io/v1/memories",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "messages": [...],
        "agent_id": "my-chatbot",
        "thread_id": "conversation-123",
        "source": "chat"
    }
)

​
Error Responses

​
Authentication Errors

{
  "detail": "Invalid authentication credentials",
  "status_code": 401
}

​
Common Error Scenarios

Causes:
  • Missing X-API-Key header
  • Invalid API key
  • API key not found in system
Response:
{
  "detail": "Invalid authentication credentials",
  "status_code": 401
}
Causes:
  • Valid API key but insufficient permissions
  • Rate limit exceeded
Response:
{
  "detail": "Insufficient permissions",
  "status_code": 403
}
Causes:
  • Rate limit exceeded
  • Too many requests in short time period
Response:
{
  "detail": "Rate limit exceeded",
  "status_code": 429,
  "retry_after": 60
}

​
Integration Examples

​
Python SDK Example

class MemSyncClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.memchat.io/v1"
        self.headers = {
            "X-API-Key": api_key,
            "Content-Type": "application/json"
        }
    
    def search_memories(self, query, limit=10):
        response = requests.post(
            f"{self.base_url}/memories/search",
            headers=self.headers,
            json={"query": query, "limit": limit}
        )
        response.raise_for_status()
        return response.json()

# Usage
client = MemSyncClient(api_key="your_api_key")
memories = client.search_memories("user interests")

​
JavaScript Example

class MemSyncClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.memchat.io/v1';
    this.headers = {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    };
  }

  async searchMemories(query, limit = 10) {
    const response = await fetch(`${this.baseUrl}/memories/search`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ query, limit })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return response.json();
  }
}

// Usage
const client = new MemSyncClient('your_api_key');
const memories = await client.searchMemories('user interests');

​
Testing Authentication

​
Validate Your API Key

def test_authentication(api_key):
    """Test if your API key is valid"""
    headers = {"X-API-Key": api_key}
    
    response = requests.get("https://api.memchat.io/healthcheck", headers=headers)
    
    if response.status_code == 200:
        print("✅ Authentication successful")
        return True
    else:
        print(f"❌ Authentication failed: {response.status_code}")
        print(response.json())
        return False

# Test your API key
test_authentication("your_api_key_here")

​
Debug Authentication Issues

def debug_auth_issues(api_key):
    """Debug common authentication problems"""
    
    # Check if API key is provided
    if not api_key:
        print("❌ API key is missing")
        return
    
    # Check API key format (should be a simple string)
    if len(api_key) < 10:
        print("❌ API key seems too short")
    else:
        print("✅ API key format looks reasonable")
    
    # Test the API key
    try:
        headers = {"X-API-Key": api_key}
        response = requests.get("https://api.memchat.io/healthcheck", headers=headers)
        
        if response.status_code == 200:
            print("✅ API key is valid")
        else:
            print(f"❌ API key validation failed: {response.status_code}")
            print(response.json())
            
    except Exception as e:
        print(f"❌ Error testing API key: {e}")

​
Next Steps

API Reference

Explore the complete API documentation with authentication examples

Quickstart

Get started with your first authenticated API calls

Integrations

Learn about authentication for external integrations

Development

Set up authentication for local development
⌘I