Skip to main content

​
Overview

Amps AI provides two environments for development and production use: Sandbox and Live. Understanding the differences and when to use each is essential for building reliable integrations.

​
Sandbox Environment

The Sandbox environment is designed for testing and development. It provides realistic device simulations without requiring real OEM credentials or physical devices.

​
Key Features

  • Realistic Device Behavior: Sandbox devices simulate real-world behavior patterns based on UTC time
  • No Real Credentials Required: Test authentication flows with mock credentials
  • Separate Data: Sandbox data is completely isolated from production
  • No Device Limits: Test with unlimited devices without subscription constraints
  • Safe Testing: Experiment without affecting real user devices or data

​
Sandbox Simulations

Sandbox devices simulate realistic behavior patterns based on UTC time:

​
Vehicles

Vehicles follow time-of-day charging patterns:
  • Morning (6-9am UTC): Vehicle likely plugged in, charging or fully charged (80-95% battery)
  • Daytime (9am-5pm UTC): Vehicle likely unplugged, battery level decreases (95% → 71%)
  • Evening (5-9pm UTC): Vehicle may be plugged in for overnight charging (70% → 50%)
  • Night (9pm-6am UTC): Vehicle plugged in, charging overnight (50% → 82%)

​
Batteries

Batteries follow solar production and usage cycles:
  • Morning (6-9am UTC): Discharging for morning load (70% → 46%)
  • Midday (9am-3pm UTC): Charging from solar production (50% → 92%)
  • Evening (3-9pm UTC): Discharging for peak usage (90% → 30%)
  • Night (9pm-6am UTC): Idle or slow charging

​
Solar Inverters

Solar inverters follow daily production patterns:
  • Night (6pm-6am UTC): No production (night mode)
  • Morning (6-9am UTC): Ramping up production
  • Midday (9am-3pm UTC): Peak production
  • Afternoon (3-6pm UTC): Declining production
  • Seasonal Variation: Production varies by month (less in winter)
Sandbox simulations use UTC time, so device behavior will match realistic patterns regardless of your local timezone. For example, vehicles will charge at night UTC, and solar inverters will produce during daylight hours UTC.

​
When to Use Sandbox

  • Development and integration testing
  • Prototyping new features
  • Testing error handling and edge cases
  • Learning the API without real devices
  • CI/CD pipeline testing
  • Demo environments

​
Live Environment

The Live environment connects to real OEM devices and production data.

​
Key Features

  • Real Device Access: Connects to actual user devices via OEM APIs
  • Production Data: All data is real and affects actual devices
  • Device Limits: Subject to subscription plan limits
  • Real Credentials: Requires valid OEM authentication
  • Production Ready: Use for customer-facing applications

​
When to Use Live

  • Production applications
  • Customer-facing integrations
  • Real device control and monitoring
  • Production data access
  • Live user connections
Always use Sandbox for development and testing. Only switch to Live when you’re ready for production and have thoroughly tested your integration.

​
URL Structure

The Link UI uses the same base URL for both environments. The environment is determined by a query parameter: Base URL: 
https://auth.amps.ai/{appId}
Sandbox: 
https://auth.amps.ai/{appId}?sandbox=true
Live: 
https://auth.amps.ai/{appId}
The sandbox query parameter accepts true or 1 to enable sandbox mode. If omitted, the environment defaults to Live.

​
Public API

The Public API uses different hostnames to determine the environment: Sandbox: 
https://sandbox-api.amps.ai
Live: 
https://api.amps.ai
The API automatically detects the environment from the hostname. If the hostname contains “sandbox”, it uses the sandbox environment.

​
API Keys

API keys are environment-specific:
  • Sandbox Keys: Format sk_sandbox_... - Only work with sandbox-api.amps.ai
  • Live Keys: Format sk_live_... - Only work with api.amps.ai
Sandbox API keys will not work with the Live API, and vice versa. Make sure you’re using the correct API key for the environment you’re targeting.

​
Environment Selection

When generating Link UI URLs for your users:
  1. For Testing: Append ?sandbox=true to the URL
  2. For Production: Use the base URL without query parameters
Example: 
// Sandbox URL
const sandboxUrl = `https://auth.amps.ai/${appId}?sandbox=true`;

// Live URL
const liveUrl = `https://auth.amps.ai/${appId}`;

​
API Requests

When making API requests:
  1. Sandbox: Use https://sandbox-api.amps.ai with a sandbox API key
  2. Live: Use https://api.amps.ai with a live API key
Example: 
# Sandbox request
curl -X GET "https://sandbox-api.amps.ai/battery/{deviceId}" \
  -H "x-api-key: sk_sandbox_abc123xyz"

# Live request
curl -X GET "https://api.amps.ai/battery/{deviceId}" \
  -H "x-api-key: sk_live_def456uvw"

​
Data Isolation

Sandbox and Live environments maintain complete data isolation:
  • Separate database schemas (sandbox.* vs live.*)
  • Separate credentials and devices
  • Separate customer data
  • No cross-environment data access
This ensures that your testing in Sandbox never affects production data or real user devices.

​
Webhook Timing

Webhook delivery timing differs between environments:
  • Sandbox: Webhooks are delivered with a 3-minute delay after action completion (configurable)
  • Live: Webhooks are typically delivered within 10 seconds after action completion
This delay in Sandbox allows you to test webhook handling without time pressure.

​
Migration from Sandbox to Live

When you’re ready to move from Sandbox to Live:
  1. Test Thoroughly: Ensure all functionality works in Sandbox
  2. Get Live API Keys: Generate live API keys from your dashboard
  3. Update URLs: Switch from sandbox-api.amps.ai to api.amps.ai
  4. Update Link UI: Remove ?sandbox=true from Link UI URLs
  5. Test with Real Devices: Connect real devices and verify behavior
  6. Monitor: Watch for any differences between sandbox and live behavior

​
Next Steps

Getting Started

Set up your first integration

API Authentication

Learn about API key authentication

Link UI Guide

Understand device authentication flow

Webhooks

Set up webhook endpoints