Authentication

Understanding MemSync authentication methods and security

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

Secure Storage

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!

Key Management

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

Error Handling

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

401 Unauthorized

Causes:

• Missing X-API-Key header
• Invalid API key
• API key not found in system

Response:

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

403 Forbidden

Causes:

• Valid API key but insufficient permissions
• Rate limit exceeded

Response:

{
  "detail": "Insufficient permissions",
  "status_code": 403
}

429 Too Many Requests

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