Authentication

Myxara uses API keys for authentication. All API requests must include your API key in the Authorization header.

API Keys

API keys are prefixed with mx_ and provide secure access to your Myxara account.

Creating an API Key

1. Log in to your Myxara dashboard
2. Navigate to API Keys
3. Click Create API Key
4. Give it a name (e.g., "Production Key")
5. Select the appropriate scopes
6. Save the key immediately - it won't be shown again!

Using API Keys

With the SDK

import { MyxaraClient } from '@myxara/sdk-js'

const client = new MyxaraClient({
  apiKey: 'mx_your_api_key_here'
})

With the REST API

curl -X GET https://api.myxara.ai/v1/inboxes \
  -H "Authorization: Bearer mx_your_api_key_here"

Scopes

API keys can be scoped to limit their permissions. This follows the principle of least privilege.

Available Scopes

Scope	Permissions
inboxes:read	List and view inboxes
inboxes:write	Create, update, and delete inboxes
messages:read	List and view messages
messages:write	Send and delete messages
webhooks:read	List and view webhooks
webhooks:write	Create, update, and delete webhooks
api_keys:read	List and view API keys
api_keys:write	Create and revoke API keys

Example: Read-Only Key

Create a key with only read permissions for monitoring:

const key = await client.apiKeys.create({
  name: 'Monitoring Key',
  scopes: ['inboxes:read', 'messages:read']
})

Example: Send-Only Key

Create a key that can only send emails:

const key = await client.apiKeys.create({
  name: 'Send-Only Key',
  scopes: ['messages:write']
})

Usage Quotas

API keys can have usage limits to prevent abuse:

const key = await client.apiKeys.create({
  name: 'Limited Key',
  scopes: ['messages:write'],
  usage_limit_per_day: 1000  // Max 1000 API calls per day
})

Checking Usage

const usage = await client.apiKeys.getUsage('key_abc123')

console.log(`Today: ${usage.today} calls`)
console.log(`This month: ${usage.this_month} calls`)

Security Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code:

// ✅ Good
const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!
})

// ❌ Bad
const client = new MyxaraClient({
  apiKey: 'mx_1234567890abcdef'
})

2. Rotate Keys Regularly

Create a new key and revoke the old one:

// Create new key
const newKey = await client.apiKeys.create({
  name: 'Production Key (2025-01)',
  scopes: ['inboxes:write', 'messages:write']
})

// Update your environment variable with newKey.key

// Revoke old key
await client.apiKeys.revoke('old_key_id')

3. Use Scoped Keys

Give each application or service its own key with minimal scopes:

// For your email sender service
const senderKey = await client.apiKeys.create({
  name: 'Email Sender',
  scopes: ['messages:write']
})

// For your webhook processor
const webhookKey = await client.apiKeys.create({
  name: 'Webhook Processor',
  scopes: ['messages:read', 'inboxes:read']
})

4. Set Usage Limits

Prevent runaway costs or abuse:

const key = await client.apiKeys.create({
  name: 'Test Key',
  scopes: ['messages:write'],
  usage_limit_per_day: 100  // Fail-safe for testing
})

5. Monitor Key Usage

Regularly check for unusual activity:

const keys = await client.apiKeys.list()

for (const key of keys.data) {
  const usage = await client.apiKeys.getUsage(key.id)

  if (usage.today > 10000) {
    console.warn(`⚠️ High usage on key: ${key.name}`)
  }
}

Rate Limiting

Myxara enforces rate limits to ensure fair usage:

• Default: 100 requests per minute
• Burst: Up to 200 requests
• Daily: 10,000 requests per day (configurable)

Handling Rate Limits

The SDK automatically retries rate-limited requests:

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  maxRetries: 5  // Retry up to 5 times
})

When rate limited, you'll receive a 429 response with Retry-After header:

import { RateLimitError } from '@myxara/sdk-js'

try {
  await client.inboxes.list()
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`)
    console.log(`Limit resets at ${error.resetAt}`)
  }
}

Revoking Keys

If a key is compromised, revoke it immediately:

Via SDK

await client.apiKeys.revoke('key_abc123')

Via Dashboard

1. Go to API Keys in your dashboard
2. Find the compromised key
3. Click Revoke

WARNING

Revoking a key is permanent and immediate. All requests using that key will fail.

Next Steps

• Quick Start - Create your first inbox
• Error Handling - Handle authentication errors
• API Keys Management - Full API reference