Authentication

All requests to the molroo API require authentication via an API key. This guide covers key management, request format, rate limits, and error handling.

Get your API key

1. Sign in to the molroo dashboard
2. Navigate to API Keys
3. Click Create Key and copy the generated key

Key format

molroo API keys use a prefix to indicate their environment:

Example: mk_live_a1b2c3d4e5f6g7h8i9j0

Using the API key

With the SDK

The SDK handles authentication automatically. Pass your key in the client config:

import { MolrooWorld } from '@molroo-ai/sdk';

const world = await MolrooWorld.create({
  baseUrl: 'https://api.molroo.io',
  apiKey: 'mk_live_xxxxx',
  llm,
});

With raw HTTP requests

Include the key in the X-API-Key header:

curl https://api.molroo.io/worlds \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json"

Rate limits

Rate limits are enforced per API key and vary by plan:

When you exceed the rate limit, the API returns a 429 status with the RATE_LIMITED error code. The response includes a Retry-After header indicating how many seconds to wait.

Origin whitelisting

For browser-based applications, you can restrict which origins are allowed to use your API key:

1. Go to API Keys in the dashboard
2. Click the key you want to configure
3. Add allowed origins (e.g., https://myapp.com)

Error responses

All authentication and authorization errors follow a consistent format:

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

Common error codes

Security best practices

• Never expose API keys in client-side code that is publicly accessible. Use a backend proxy or server-side rendering.
• Use mk_test_ keys during development to avoid unexpected billing.
• Rotate keys periodically by creating a new key, updating your application, and revoking the old key.
• Configure origin whitelisting for any key used in browser environments.
• Use environment variables to store keys, never hardcode them in source code:

# .env
MOLROO_API_KEY=mk_live_xxxxx

const world = await MolrooWorld.create({
  baseUrl: 'https://api.molroo.io',
  apiKey: process.env.MOLROO_API_KEY!,
  llm,
});