Authentication

Mercury uses API key authentication to secure all endpoints. This guide covers how to obtain, use, and manage your API keys securely.

API Key Authentication

How It Works

All API requests to Mercury must include an API key in the request headers. The API key identifies your application and determines your access permissions and rate limits.

Header Format

x-hermes-api-key: YOUR_API_KEY_HERE

Complete Request Example

curl -X GET \
  'https://your-api-name.mercury.ratiomachina.com/personas' \
  -H 'Content-Type: application/json' \
  -H 'x-hermes-api-key: hk_1234567890abcdef...'

JavaScript/Node.js Example

const response = await fetch('/api/personas', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-hermes-api-key': process.env.MERCURY_API_KEY
  }
});

Python Example

import requests

headers = {
    'Content-Type': 'application/json',
    'x-hermes-api-key': 'your_api_key_here'
}

response = requests.get(
    'https://your-mercury-api.../personas', 
    headers=headers
)

⚠️ Security Warning

Never expose your API keys in client-side code, public repositories, or browser applications. Always use environment variables or secure credential management systems.

API Key Management

Obtaining API Keys

Steps to Get Your API Key

1. Log into your Mercury account
2. Navigate to Settings → API Keys
3. Click "Generate New API Key"
4. Copy the key immediately (it won't be shown again)
5. Store it securely in your application

API Key Format

hk_1234567890abcdef1234567890abcdef12345678

Mercury API keys always start with hk_ followed by 40 characters of alphanumeric data.

Key Rotation & Management

Best Practices

Regular Rotation: Rotate keys every 90 days or after security incidents
Environment Separation: Use different keys for development, staging, and production
Least Privilege: Request minimum permissions needed for your use case
Monitoring: Monitor API key usage and set up alerts for unusual activity

Key States

Active

Key is valid and can make API calls

Deprecated

Key works but should be replaced soon

Revoked

Key is disabled and will not work

Environment Variables Setup

Node.js / Next.js

.env.local

MERCURY_API_KEY=hk_1234567890abcdef...
MERCURY_BASE_URL=https://your-mercury-api.../prod

Usage in Code

const apiKey = process.env.MERCURY_API_KEY;
const baseUrl = process.env.MERCURY_BASE_URL;

if (!apiKey) {
  throw new Error('MERCURY_API_KEY not found');
}

Python

.env

MERCURY_API_KEY=hk_1234567890abcdef...
MERCURY_BASE_URL=https://your-mercury-api.../prod

Usage in Code

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('MERCURY_API_KEY')
base_url = os.getenv('MERCURY_BASE_URL')

if not api_key:
    raise ValueError('MERCURY_API_KEY not found')

Rate Limits & Quotas

Default Rate Limits

REST API Endpoints1000/hour

Standard CRUD operations

RPC API Endpoints500/hour

Complex operations like /conversations

AI Generation200/hour

Message generation and skill execution

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1642694400
X-RateLimit-Window: 3600

Limit: Total requests allowed in the window

Remaining: Requests left in current window

Reset: Unix timestamp when window resets

Window: Rate limit window in seconds

Handling Rate Limits

429 Response Example

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642698000
Retry-After: 3600

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Limit: 1000/hour",
  "retryAfter": 3600
}

Retry Logic Example

async function callMercuryAPI(url, options) {
  try {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      await new Promise(resolve => 
        setTimeout(resolve, retryAfter * 1000)
      );
      return callMercuryAPI(url, options);
    }
    
    return response;
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Error Handling

Authentication Errors

401 Unauthorized

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked"
}

403 Forbidden

{
  "error": "Insufficient permissions",
  "code": "INSUFFICIENT_PERMISSIONS", 
  "message": "API key does not have permission for this operation"
}

Common Authentication Issues

Missing API Key

Problem: Request doesn't include the x-hermes-api-key header

Solution: Ensure every request includes the header with your valid API key

Invalid API Key Format

Problem: API key doesn't match expected format (hk_followed by 40 chars)

Solution: Double-check you've copied the complete API key from Mercury UI

Revoked or Expired Key

Problem: API key was revoked in Mercury UI or has expired

Solution: Generate a new API key and update your application configuration

Security Best Practices

✅ Do

Store keys in environment variables: Never hardcode API keys in your source code
Use HTTPS only: Always make API calls over secure connections
Rotate keys regularly: Update API keys every 90 days minimum
Monitor usage: Track API calls for unusual patterns
Use different keys per environment: Separate dev/staging/production keys
Implement proper error handling: Handle auth failures gracefully

❌ Don't

Commit keys to version control: Use .gitignore for environment files
Expose keys in client-side code: Never send API keys to browsers
Share keys between applications: Each app should have its own key
Log API keys: Avoid including keys in log files
Use keys in URLs: Always use headers for authentication
Ignore rate limits: Respect API limits to avoid blocking

Ready to Start Building?

Now that you understand Mercury's authentication system, you're ready to start integrating with the API. Begin with the Conversation Design endpoints to create your first personas and conversations.

REST API Guide →RPC API Guide →Quickstart Guide →