Authentication

InstaVM uses API keys for the CLI, SDKs, and raw HTTP requests.

Get an API Key

1. Sign up at the InstaVM Dashboard
2. Navigate to the API Keys section
3. Create a new key
4. Copy the key that starts with instavm_sk_...

Keep Your API Key Secure

Never commit API keys to version control or share them publicly. Treat them like passwords.

CLI Authentication

pip install instavm
instavm auth set-key
instavm auth status
instavm whoami

instavm auth set-key stores the key in ~/.instavm/config.json. Use instavm auth logout to remove the stored key.

Environment Variables

For automation, CI, and ephemeral environments, prefer INSTAVM_API_KEY:

export INSTAVM_API_KEY="instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Then use it in your code:

CLI

# The CLI picks up INSTAVM_API_KEY automatically
export INSTAVM_API_KEY="instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Verify
instavm auth status

Python

import os
from instavm import InstaVM

api_key = os.getenv("INSTAVM_API_KEY")
client = InstaVM(api_key)

JavaScript

const { InstaVM } = require('instavm');

const apiKey = process.env.INSTAVM_API_KEY;
const client = new InstaVM(apiKey);

Direct Usage

You can also pass the API key directly, although environment variables or stored CLI config are better for real deployments:

CLI

# Store key interactively
instavm auth set-key

# Or pipe it in
echo "instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | instavm auth set-key

Python

from instavm import InstaVM

client = InstaVM("instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

JavaScript

const { InstaVM } = require('instavm');

const client = new InstaVM("instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

Raw HTTP Requests

The current API uses the X-API-Key header:

curl https://api.instavm.io/v1/vms \
  -H "X-API-Key: instavm_sk_..."

API Key Management

Creating Multiple Keys

Create separate keys for different environments and label them by use case:

• Production -- store in your production environment or secret manager
• Development -- use for local CLI and SDK work
• Testing -- isolate test traffic and rotation

Rotating Keys

1. Generate a new API key
2. Update your application or CLI configuration
3. Test the new key
4. Delete the old key

Key Permissions

Currently, all API keys have full access to your account. Future versions will support scoped permissions.

Authentication Errors

Common authentication errors and fixes:

Invalid API Key

AuthenticationError: Invalid API key or session expired

Fixes:

• Verify the key is correct
• Check for extra spaces or truncated characters
• Confirm the key has not been deleted

Session Expired

SessionError: Session expired

Fixes:

• Start a new session
• Check your session timeout settings

Rate Limited

RateLimitError: Rate limit exceeded

Fixes:

• Wait before making more requests
• Implement exponential backoff
• Contact support for higher limits

Security Best Practices

Storage

• Use environment variables or secret managers
• Keep configuration files out of version control
• Never hardcode keys in source files
• Delete unused keys

Usage

• Use HTTPS for all API calls
• Rotate keys regularly
• Monitor usage for anomalies
• Use separate keys for production and development

Example: Secure Configuration

CLI

# Source key from a secret manager or file
export INSTAVM_API_KEY=$(cat /run/secrets/instavm_key)

# Override per-command without changing stored config
instavm ls --api-key "instavm_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Python

# config.py
import os
from dataclasses import dataclass

@dataclass
class Config:
    instavm_api_key: str = os.getenv("INSTAVM_API_KEY")

    def __post_init__(self):
        if not self.instavm_api_key:
            raise ValueError("INSTAVM_API_KEY environment variable required")

# main.py
from instavm import InstaVM
from config import Config

config = Config()
client = InstaVM(config.instavm_api_key)

JavaScript

// config.js
require('dotenv').config();

const config = {
  instavmApiKey: process.env.INSTAVM_API_KEY,
};

if (!config.instavmApiKey) {
  throw new Error('INSTAVM_API_KEY environment variable required');
}

module.exports = config;

// main.js
const { InstaVM } = require('instavm');
const config = require('./config');

const client = new InstaVM(config.instavmApiKey);

Next Steps

• CLI
• Quickstart
• Python SDK
• TypeScript SDK