Powered by

# API Keys

Learn how to generate, manage, and use API keys for authenticating with the microsandbox server.

# Overview

API keys provide secure authentication for accessing the microsandbox server. They are required for all API operations unless the server is running in development mode.

# Generating API Keys

# Basic Key Generation

Generate a new API key with default settings:

msb server keygen

This creates an API key with:

  • No expiration (permanent until manually revoked)
  • Global access to all namespaces
  • Full permissions for all sandbox operations

# Key with Expiration

Generate an API key that expires after a specific duration:

msb server keygen --expire 3mo

Supported Duration Formats:

  • s - seconds (e.g., 30s)
  • m - minutes (e.g., 15m)
  • h - hours (e.g., 24h)
  • d - days (e.g., 7d)
  • w - weeks (e.g., 2w)
  • mo - months (e.g., 3mo)
  • y - years (e.g., 1y)

Examples:

# Expires in 1 hour
msb server keygen --expire 1h

# Expires in 7 days
msb server keygen --expire 7d

# Expires in 6 months
msb server keygen --expire 6mo

# Namespace-Specific Keys

Generate an API key limited to a specific namespace:

msb server keygen --namespace team-alpha

This key will only have access to sandboxes running in the team-alpha namespace.

# Combined Options

Generate a namespace-specific key with expiration:

msb server keygen --expire 1w --namespace project-web

# Using API Keys

# Environment Variable (Recommended)

Set the API key as an environment variable:

export MSB_API_KEY="your-api-key-here"

Add this to a .env file for persistence:

echo 'MSB_API_KEY="your-api-key-here"' >> .env

# SDK Configuration

Python SDK:

from microsandbox import PythonSandbox

# Using environment variable (recommended)
async with PythonSandbox.create(name="my-sandbox") as sb:
    # API key automatically loaded from MSB_API_KEY
    pass

# Explicit API key
async with PythonSandbox.create(
    name="my-sandbox",
    api_key="your-api-key-here"
) as sb:
    pass

TypeScript SDK:

import { PythonSandbox } from 'microsandbox';

// Using environment variable (recommended)
const sandbox = await PythonSandbox.create({
  name: 'my-sandbox'
  // API key automatically loaded from MSB_API_KEY
});

// Explicit API key
const sandbox = await PythonSandbox.create({
  name: 'my-sandbox',
  apiKey: 'your-api-key-here'
});

# HTTP API Requests

Include the API key in the Authorization header:

curl -X POST http://127.0.0.1:5555/api/v1/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sandbox.start",
    "params": {
      "sandbox": "my-env",
      "namespace": "default"
    },
    "id": "1"
  }'

# Development Mode

For development and testing, you can skip API key requirements:

msb server start --dev

Development Mode Features:

  • No authentication required
  • Faster setup for local development
  • All operations permitted without API keys

# Key Management

# Checking Server Status

Verify if the server requires authentication:

msb server status

# Regenerating Keys

To generate a new API key (previous keys remain valid):

msb server keygen --expire 30d

# Resetting Server Key

To invalidate all existing API keys and generate a new server key:

msb server start --reset-key

This will:

  • Invalidate all existing API keys
  • Generate a new server signing key
  • Require new API key generation

# Security Best Practices

guide