> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Authenticate via x-api-key header against api.amps.ai. The key prefix selects the environment: sk_test_ for sandbox, sk_live_ for live.

## API key authentication

Every Amps API request carries an API key in the `x-api-key` header. The key identifies the customer account and routes the request to the correct environment schema.

## Getting your API keys

<Info>
  You will need to request Sandbox access before completing these steps. [Get sandbox access](https://tally.so/r/D4zgZE) to continue.
</Info>

<Steps>
  <Step title="Log into Dashboard">
    Access the [Amps AI Dashboard](https://app.amps.ai) with your customer account
  </Step>

  <Step title="Navigate to API Keys">
    Go to the API Keys section in your account settings
  </Step>

  <Step title="Generate Keys">
    Create separate API keys for sandbox and/or live environments
  </Step>
</Steps>

<Warning>
  Keep your API keys secure. Never commit them to version control or expose them in client-side code.
</Warning>

## Using API keys

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

```bash theme={null}
x-api-key: your-api-key-here
```

### Example request

```bash curl theme={null}
curl -X GET "https://api.amps.ai/battery/{deviceId}" \
  -H "x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"
```

## Environment-specific keys

API keys are environment-specific. The prefix selects the environment; the host is always `https://api.amps.ai`:

* **Sandbox Keys** (`sk_test_...`): route to sandbox simulations
* **Live Keys** (`sk_live_...`): route to real OEM hardware

The environment is stamped into the key at issuance and cannot be overridden per request. A sandbox key never reaches live data, and a live key never reaches sandbox data.

<Tip>
  Always use sandbox keys during development and testing. Only switch to live keys when you're ready for production.
</Tip>

<Card title="Environments Guide" icon="info" href="/get-started/environments">
  Learn more about Sandbox and Live environments, including URL structure and when to use each
</Card>

## API key format

API keys follow this format:

```
sk_{environment}_{random_string}
```

The `{environment}` segment is `test` for sandbox keys and `live` for live keys.

Examples:

* `sk_test_xxxxxxxxxxxxxxxxxxxxxxxx`
* `sk_live_xxxxxxxxxxxxxxxxxxxxxxxx`

## Base URL

Both environments share one base URL:

```
https://api.amps.ai
```

The key you send, not the URL, selects sandbox or live.

## Error responses

### Invalid API key

<ResponseField name="401" type="object">
  Invalid or missing API key

  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Invalid or missing API key"
    },
    "meta": {
      "requestId": "req_abc123",
      "timestamp": "2026-06-01T10:30:00.000Z",
      "path": "/battery/device_abc123",
      "latencyMs": 8
    }
  }
  ```
</ResponseField>

### Expired API key

<ResponseField name="401" type="object">
  API key has been revoked or expired

  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "EXPIRED_TOKEN",
      "message": "API key has expired"
    },
    "meta": {
      "requestId": "req_abc123",
      "timestamp": "2026-06-01T10:30:00.000Z",
      "path": "/battery/device_abc123",
      "latencyMs": 8
    }
  }
  ```
</ResponseField>

## Best practices

<AccordionGroup>
  <Accordion title="Key Rotation">
    Regularly rotate your API keys for security. Generate new keys and update your applications before revoking old ones.
  </Accordion>

  <Accordion title="Key Naming">
    Use descriptive names for your API keys (e.g., "Production App", "Staging Environment") to track usage.
  </Accordion>

  <Accordion title="Environment Separation">
    Never use live API keys in development or testing environments. Always use sandbox keys for non-production use.
  </Accordion>

  <Accordion title="Key Storage">
    Store API keys securely:

    * Use environment variables
    * Never hardcode in source code
    * Use secret management services
    * Restrict access to keys
  </Accordion>
</AccordionGroup>

## 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

<Warning>
  Revoking an API key will immediately break all applications using that key. Make sure you have replacement keys ready.
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="Environments Guide" icon="info" href="/get-started/environments">
    Learn about Sandbox and Live environments
  </Card>

  <Card title="Link UI" icon="link" href="/guides/link-ui/getting-started">
    Learn about device authentication
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore API endpoints
  </Card>
</CardGroup>