Skip to main content

​
API Key Authentication

All API requests require an API key in the request header. The API key identifies your customer account and authorizes access to your devices and data.

​
Getting Your API Keys

You will need to request Sandbox access before completing these steps. Get sandbox access to continue.
1

Log into Dashboard

Access the Amps AI Dashboard with your customer account
2

Navigate to API Keys

Go to the API Keys section in your account settings
3

Generate Keys

Create separate API keys for sandbox and/or live environments
Keep your API keys secure. Never commit them to version control or expose them in client-side code.

​
Using API Keys

Include your API key in the x-api-key header for all requests: 
x-api-key: your-api-key-here

​
Example Request

curl
curl -X GET "https://api.amps.ai/battery/{deviceId}" \
  -H "x-api-key: sk_live_abc123xyz" \
  -H "Content-Type: application/json"

​
Environment-Specific Keys

API keys are environment-specific and must match the API hostname you’re using:
  • Sandbox Keys (sk_sandbox_...): Use with https://sandbox-api.amps.ai
  • Live Keys (sk_live_...): Use with https://api.amps.ai
Always use sandbox keys during development and testing. Only switch to live keys when you’re ready for production.

Environments Guide

Learn more about Sandbox and Live environments, including URL structure and when to use each

​
API Key Format

API keys follow this format: 
sk_{environment}_{random_string}
Examples:
  • sk_sandbox_abc123xyz
  • sk_live_def456uvw

​
Base URLs

Use the appropriate base URL for your environment:

​
Sandbox

https://sandbox-api.amps.ai

​
Live

https://api.amps.ai

​
Error Responses

​
Invalid API Key

​
401
object
Invalid or missing API key
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-23T10:30:00.000Z",
    "path": "/battery/device_abc123"
  }
}

​
Expired API Key

​
401
object
API key has been revoked or expired
{
  "success": false,
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "API key has been revoked"
  }
}

​
Best Practices

Regularly rotate your API keys for security. Generate new keys and update your applications before revoking old ones.
Use descriptive names for your API keys (e.g., “Production App”, “Staging Environment”) to track usage.
Never use live API keys in development or testing environments. Always use sandbox keys for non-production use.
Store API keys securely:
  • Use environment variables
  • Never hardcode in source code
  • Use secret management services
  • Restrict access to keys

​
Revoking API Keys

You can revoke API keys at any time from the dashboard:
  1. Navigate to API Keys section
  2. Find the key you want to revoke
  3. Click “Revoke”
  4. The key will immediately stop working
Revoking an API key will immediately break all applications using that key. Make sure you have replacement keys ready.

​
Rate Limits

API keys are subject to rate limits based on your plan:
  • Sandbox: More lenient limits for testing
  • Live: Production limits based on your subscription
Rate limit headers are included in responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

​
Next Steps

Environments Guide

Learn about Sandbox and Live environments

Link UI

Learn about device authentication

API Reference

Explore API endpoints