Authentication

Secure API access

All Motte API endpoints require authentication using API keys. Learn how to obtain, manage, and use your API keys securely.

API Key Authentication

Motte uses API key authentication for all requests. Your API key identifies your account and provides access to your resources. Always keep your API keys secure and never expose them in client-side code.

Getting Your API Key

Step 1: Sign Up

Create an account at motte.ai if you haven't already.

Step 2: Access Dashboard

Navigate to your account dashboard and go to the "API Keys" section.

Step 3: Generate Key

Click "Generate New API Key" and give it a descriptive name for easy identification.

Step 4: Secure Storage

Copy your API key immediately and store it securely. You won't be able to see it again.

Using Your API Key

Include your API key in the Authorization header of every request using the Bearer token format:

HTTP Header

Authorization: Bearer YOUR_API_KEY_HERE

Example Requests

cURL Example

curl -X POST https://api.motte.ai/api/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "customer support best practices",
    "limit": 5
  }'

JavaScript Example

const response = await fetch('https://api.motte.ai/api/memory/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'customer support best practices',
    limit: 5
  })
});

const data = await response.json();

Python Example

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
}

data = {
    'query': 'customer support best practices',
    'limit': 5
}

response = requests.post(
    'https://api.motte.ai/api/memory/search',
    headers=headers,
    json=data
)

result = response.json()

Security Best Practices

Environment Variables

Store API keys in environment variables, never hardcode them in your source code.

# .env file
MOTTE_API_KEY=your_api_key_here

# In your code
const apiKey = process.env.MOTTE_API_KEY;

Key Rotation

Regularly rotate your API keys, especially if you suspect they may have been compromised.

Scope Limitation

Use different API keys for different environments (development, staging, production) and limit their scope when possible.

Monitoring

Monitor your API key usage regularly and set up alerts for unusual activity patterns.

Error Responses

401 Unauthorized

Missing or invalid API key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided"
  }
}

403 Forbidden

API key doesn't have required permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission to access this resource"
  }
}

429 Too Many Requests

Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retry_after": 60
  }
}

Rate Limits

Endpoint Category	Rate Limit	Burst Limit
General API	1000/hour	100/minute
Training API	10/hour	5/minute
Memory API	5000/hour	500/minute
Monitoring API	2000/hour	200/minute