Authentication

All Akira API requests require authentication using an API key.

Getting an API Key

To obtain an API key:

1. Sign up at app.akiralabs.ai (opens in a new tab)
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Copy and securely store your key

You can also use the platform directly to create and manage sandboxes through the web interface.

Using Your API Key

HTTP Header

Include your API key in the x-api-key header:

curl https://api.akiralabs.ai/v1/sandboxes/list \
  -H "x-api-key: YOUR_API_KEY"

Query Parameter

Alternatively, include your API key as a query parameter:

curl "https://api.akiralabs.ai/v1/sandboxes/list?api_key=YOUR_API_KEY"

The header method is preferred for security reasons.

TypeScript SDK

The SDK accepts your key directly or via environment variable:

import SandboxSDK from '@akiralabs/sandbox-sdk';
 
// Option 1: Explicit key
const client = new SandboxSDK({
  apiKey: 'YOUR_API_KEY',
});
 
// Option 2: Environment variable (recommended)
const client = new SandboxSDK({
  apiKey: process.env['AKIRA_API_KEY'],
});

Error Handling

The SDK provides typed errors for different failure scenarios:

import SandboxSDK from '@akiralabs/sandbox-sdk';
 
try {
  await client.sandboxes.list();
} catch (err) {
  if (err instanceof SandboxSDK.APIError) {
    console.log(err.status, err.name, err.headers);
  }
}

Environment Variables

Store your key as an environment variable:

# .env (add to .gitignore!)
AKIRA_API_KEY=your_api_key_here

# Shell
export AKIRA_API_KEY=your_api_key_here

Key Management

Best Practices

1. Never hardcode keys - Use environment variables
2. Rotate regularly - Generate new keys periodically
3. Use separate keys - Different keys for dev/staging/production
4. Monitor usage - Watch for unexpected activity
5. Revoke compromised keys - Immediately disable leaked keys

Rotating Keys

To rotate a key:

1. Create a new API key in the dashboard
2. Update your application to use the new key
3. Verify the new key works
4. Delete the old key

Revoking Keys

If a key is compromised:

1. Go to Settings → API Keys in the dashboard
2. Find the compromised key
3. Click Revoke
4. The key is immediately invalidated

Error Responses

Missing Key

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key. Include your key in the x-api-key header."
  }
}

Invalid Key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Check that your key is correct and active."
  }
}

Revoked Key

{
  "error": {
    "code": "unauthorized",
    "message": "This API key has been revoked."
  }
}

Security Recommendations

CI/CD Environments

Use secrets management for CI/CD:

GitHub Actions:

env:
  AKIRA_API_KEY: ${{ secrets.AKIRA_API_KEY }}

GitLab CI:

variables:
  AKIRA_API_KEY: $AKIRA_API_KEY

Server Applications

Use environment variables or secrets managers:

// Node.js with dotenv
import 'dotenv/config';
 
const client = new SandboxSDK({
  apiKey: process.env.AKIRA_API_KEY,
});

Client Applications

// BAD: Key exposed in frontend
const client = new SandboxSDK({
  apiKey: 'sk_live_abc123', // Anyone can see this!
});
 
// GOOD: Call your backend which has the key
const response = await fetch('/api/sandbox/create', {
  method: 'POST',
});

Next Steps

• API Introduction - Request/response format
• API Reference - Interactive documentation
• Quickstart - Create your first sandbox