Authentication

The Mirra SDK uses API keys for authentication. All API requests must include an API key in the Authorization header using the Bearer authentication scheme.

Getting your API key

API keys are automatically generated when you create scripts or resources in Mirra. The most common way to obtain an API key is by creating a script.

Creating a script and getting an API key

When you create a script via the API or web interface, an API key is automatically generated and returned in the response. This key is only shown once—save it securely as you cannot retrieve it later.

Example: Creating a script via API

curl https://api.fxn.world/api/sdk/v1/scripts \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Script",
    "description": "A simple echo script",
    "runtime": "nodejs18",
    "code": "async function main(params) { return { success: true, input: params }; } module.exports = { main };"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "673abc123def456789",
    "name": "My First Script",
    "apiKey": "mirra_script_a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789"
  }
}

The apiKey field contains your authentication credential. Store it securely in environment variables or a secrets manager.

Creating a script via the web interface

You can also obtain an API key through the browser-based developer dashboard:

1. Navigate to https://store.getmirra.app/developer/scripts
2. Click Create New Script
3. Complete the script creation wizard
4. Your API key is displayed after script creation—copy it immediately

The web interface provides the same functionality as the API, making it easier to get started without writing code.

API key format

Mirra API keys use prefixes to identify their type and context:

• mirra_script_ - Keys associated with scripts you create
• mirra_install_ - Keys for installed script instances (Lambda execution)
• mirra_test_ - Test environment keys for development

API keys are 64 to 128 characters long and contain hexadecimal characters after the prefix.

Example API keys:

mirra_script_a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789
mirra_install_f9e8d7c6b5a4321fedcba9876543210fedcba9876543210fedcba9876543210

Using API keys

Include your API key in the Authorization header with the Bearer scheme for every API request:

curl https://api.fxn.world/api/sdk/v1/scripts \
  -H "Authorization: Bearer mirra_script_a1b2c3d4e5f6..."

In application code

Node.js:

const response = await fetch('https://api.fxn.world/api/sdk/v1/scripts', {
  headers: {
    'Authorization': `Bearer ${process.env.MIRRA_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

Load the API key from an environment variable rather than hardcoding it in your source code.

Python:

import os
import requests
 
headers = {
    'Authorization': f'Bearer {os.environ["MIRRA_API_KEY"]}',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://api.fxn.world/api/sdk/v1/scripts',
    headers=headers
)

Security best practices

Store keys securely

Store API keys in environment variables, not in source code:

# .env
MIRRA_API_KEY=mirra_script_a1b2c3d4e5f6...

// Load from environment
const apiKey = process.env.MIRRA_API_KEY;

Never hardcode API keys:

// ❌ BAD: Hardcoded API key
const apiKey = 'mirra_script_a1b2c3d4e5f6...';
 
// ✅ GOOD: Load from environment
const apiKey = process.env.MIRRA_API_KEY;

Regenerate compromised keys

If an API key is accidentally exposed or compromised, regenerate it immediately:

1. Create a new version of your script to get a fresh API key
2. Update your applications to use the new key
3. Test that all systems work with the new key
4. The old script version and its key become inactive

Separate keys for different environments

Create separate scripts for development, staging, and production environments. Each script receives its own API key, providing isolation between environments:

# Development
MIRRA_API_KEY_DEV=mirra_script_dev123...
 
# Production
MIRRA_API_KEY_PROD=mirra_script_prod456...

This limits the impact if a development key is compromised—production resources remain secure.

Limit key exposure

Minimize the number of places where API keys are stored or transmitted:

• Use environment variables in server-side applications
• Store keys in secure secrets managers (AWS Secrets Manager, HashiCorp Vault)
• Never log API keys in application logs
• Avoid passing keys as URL parameters
• Never expose keys in client-side code (browsers, mobile apps)

Monitor usage

Regularly review your scripts and their activity:

• Check deployment logs for unusual patterns
• Monitor execution frequency and error rates
• Review which scripts are actively using their API keys
• Delete unused scripts to reduce attack surface

Rate limits

API requests are rate-limited per API key to ensure fair usage and system stability:

Rate limit headers

Rate limit information is included in response headers for every API request:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800

• X-RateLimit-Limit - Maximum requests allowed in the current window
• X-RateLimit-Remaining - Requests remaining in the current window
• X-RateLimit-Reset - Unix timestamp when the rate limit resets

Rate limit errors

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 42 seconds.",
    "retryAfter": 42
  }
}

The retryAfter field indicates how many seconds to wait before retrying. Implement exponential backoff in your application to handle rate limits gracefully.

Authentication with session tokens

Some operations, particularly when using the web interface, use session tokens instead of script API keys. Session tokens are obtained by logging into the Mirra platform and are used for account-level operations.

When to use session tokens:

• Creating new scripts via the API (to obtain an API key)
• Managing your developer profile
• Accessing marketplace features
• Administrative operations on your account

When to use script API keys:

• Executing deployed scripts
• Calling resource methods
• Automated workflows and integrations
• Production applications

Session tokens typically have shorter expiration times than API keys and are managed automatically by the web interface.

Troubleshooting

401 Unauthorized

Your API key is missing, invalid, or associated with an inactive script.

Common causes:

• Missing Authorization header
• Invalid API key format
• Script has been deleted or deactivated
• API key was not copied correctly from creation response

Solutions:

• Verify the header format: Authorization: Bearer YOUR_KEY
• Check that your API key starts with mirra_script_ or mirra_install_
• Ensure the script associated with the key is still active
• If the key is lost, create a new script version to get a new key

Invalid API key format

API keys must meet these requirements:

• Start with mirra_script_, mirra_install_, or mirra_test_
• Be 64 to 128 characters long after the prefix
• Contain only lowercase letters and hexadecimal characters (a-f, 0-9)

If your API key does not meet these requirements, it may have been truncated or modified. Retrieve the full key from the script creation response.

Missing Authorization header

The API returns a 401 Unauthorized error if the Authorization header is missing:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authorization header"
  }
}

Ensure every API request includes the header with the correct format:

-H "Authorization: Bearer YOUR_API_KEY"

See also

• Quickstart - Create your first script and get an API key
• Error Codes - Complete error reference
• Scripts - Deploy serverless functions
• Resources - Create API integrations