Authentication

All MemoryRelay API requests require authentication via an API key. This page covers how to obtain a key, how to include it in requests, and how scopes and rate limits work.

Getting an API Key

1. Sign up or log in at app.memoryrelay.ai
2. Navigate to Settings > API Keys in the dashboard
3. Click Create API Key
4. Give it a descriptive name (e.g., "dev-assistant-prod") and select the scopes you need
5. Copy the key immediately -- it is only shown once

warning

API keys are displayed only at creation time. If you lose a key, you must create a new one. Store keys securely in environment variables or a secrets manager -- never commit them to source control.

API keys follow the format mem_ followed by a random string (e.g., mem_a1b2c3d4e5f6...). The key is SHA-256 hashed before storage -- MemoryRelay never stores your raw key.

Authentication Methods

MemoryRelay supports two authentication methods. Use whichever fits your integration.

Bearer Token (recommended)

Include the key in the Authorization header:

curl https://api.memoryrelay.net/v1/agents \
  -H "Authorization: Bearer mem_your_api_key_here"

X-API-Key Header

Alternatively, use the X-API-Key header:

curl https://api.memoryrelay.net/v1/agents \
  -H "X-API-Key: mem_your_api_key_here"

info

Both methods are fully equivalent. The Bearer token approach is standard for REST APIs and is preferred for most integrations. The X-API-Key header is provided for compatibility with tools that have specific header requirements.

Scopes

API keys use scope-based authorization to control what operations are permitted. Each key can have one or more of the following scopes:

Scope	Permissions
read	List and retrieve agents, memories, entities, sessions, decisions, patterns, projects
write	Create and update agents, memories, entities, sessions, decisions, patterns, projects
delete	Delete agents, memories, entities, sessions, decisions, patterns, projects
admin	Full access including API key management and maintenance operations

A key with read + write scopes can create and retrieve memories but cannot delete them. A key with only read scope is useful for dashboards or monitoring tools that should never modify data.

tip

Follow the principle of least privilege. Give each key only the scopes it needs. A production agent that stores and searches memories only needs read + write. Reserve admin scope for management tools.

Scope Errors

If a request requires a scope that your key does not have, the API returns 403 Forbidden:

{
  "type": "authorization_error",
  "message": "Insufficient scope. Required: write",
  "code": 403,
  "request_id": "req_abc123"
}

Key Expiration

API keys can be created with an optional expiration date. Expired keys are automatically rejected. The API returns 401 Unauthorized for expired keys with a message indicating the key has expired.

Check key status and last usage time in the dashboard under Settings > API Keys.

Rate Limiting

MemoryRelay enforces rate limits to ensure fair usage and service stability.

Limit	Value
Default rate	100 requests per minute per API key

Rate Limit Headers

Every response includes headers indicating your current rate limit status:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (only on 429 responses)

Handling Rate Limits

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "type": "rate_limit_error",
  "message": "Rate limit exceeded. Try again in 32 seconds.",
  "code": 429,
  "request_id": "req_def456"
}

Example with retry logic:

# Check rate limit headers in the response
curl -i https://api.memoryrelay.net/v1/memories \
  -H "Authorization: Bearer mem_your_api_key_here"

# Response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 47
# X-RateLimit-Reset: 1710700800

Python SDK Authentication

The Python SDK handles authentication automatically.

Explicit API Key

from memoryrelay import MemoryRelay

client = MemoryRelay(api_key="mem_your_api_key_here")

Environment Variable

Set MEMORYRELAY_API_KEY and the SDK picks it up automatically:

export MEMORYRELAY_API_KEY="mem_your_api_key_here"

from memoryrelay import MemoryRelay

client = MemoryRelay()  # reads MEMORYRELAY_API_KEY from environment

Async Client

The same authentication works with the async client:

from memoryrelay import AsyncMemoryRelay

async with AsyncMemoryRelay(api_key="mem_your_api_key_here") as client:
    agents = await client.agents.list()

Error Handling

The SDK raises typed exceptions for authentication failures:

from memoryrelay import MemoryRelay, AuthenticationError, RateLimitError

try:
    client = MemoryRelay()  # no key set anywhere
except AuthenticationError as e:
    print(f"Auth failed: {e}")
    # "API key is required. Provide via api_key parameter or
    #  MEMORYRELAY_API_KEY environment variable."

from memoryrelay import MemoryRelay, MemorySearchRequest, RateLimitError
import time

client = MemoryRelay(api_key="mem_your_api_key_here")

try:
    results = client.memories.search(MemorySearchRequest(
        query="deployment process",
        agent_id="agent-123"
    ))
except RateLimitError as e:
    print(f"Rate limited: {e}")
    time.sleep(30)  # back off and retry

curl Examples

Store a Memory

curl -X POST https://api.memoryrelay.net/v1/memories \
  -H "Authorization: Bearer mem_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-123",
    "content": "The user prefers TypeScript over JavaScript for new projects."
  }'

Search Memories

curl -X POST https://api.memoryrelay.net/v1/memories/search \
  -H "Authorization: Bearer mem_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What programming language does the user prefer?",
    "agent_id": "agent-123",
    "limit": 5
  }'

List Agents

curl https://api.memoryrelay.net/v1/agents \
  -H "Authorization: Bearer mem_your_api_key_here"

Health Check (no auth required)

curl https://api.memoryrelay.net/v1/health

Request Tracing

Every API response includes an X-Request-ID header for distributed tracing. You can also provide your own request ID:

curl https://api.memoryrelay.net/v1/agents \
  -H "Authorization: Bearer mem_your_api_key_here" \
  -H "X-Request-ID: my-trace-id-123"

The same request ID appears in error responses, making it straightforward to correlate client-side errors with server-side logs.