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

# Testing in sandbox

> Run through a full Axle VPP integration in sandbox before going to production

This page walks you through testing every part of the [integration](https://docs.axle.energy/workflows/axle-vpp/integration.md) end to end
against `https://api-sandbox.axle.energy`. You'll onboard a battery, send telemetry for it, then
have us send dispatch and opt-out webhooks to your endpoint.

Sandbox and production are kept fully apart. Identifiers, tokens and webhook signing keys from one
won't work in the other.

## Requirements

Before you start, [get in touch](mailto:hello@axle.energy) and we'll set you up with:

| Requirement | What it's for |
| - | - |
| **Sandbox API credentials** | A `username` and `password` you exchange for a bearer token, used on every request below. |
| **Webhook signing key** | Your secret for [verifying the signature](https://docs.axle.energy/workflows/webhooks.md#verifying-the-signature) on every webhook we send. We share it securely. |
| **Webhook URL registered with Axle** | The sandbox endpoint you want `vpp:dispatch:requested` and `vpp:site:opted_out` delivered to, plus `vpp:asset:registered` if you're using Axle's signup flow. See [Registering your endpoint](https://docs.axle.energy/workflows/webhooks.md#registering-your-endpoint). |

Once you have your credentials, exchange them for a token:

```bash theme={null}
curl -sS -X POST https://api-sandbox.axle.energy/auth/token-form \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=$AXLE_USERNAME" \
  --data-urlencode "password=$AXLE_PASSWORD"
```

Take `access_token` from the response and export it as `AXLE_TOKEN` for the requests below.
Tokens expire after an hour, so request a new one when you get a `401`. See
[Authentication](https://docs.axle.energy/workflows/axle-vpp/api-reference/auth.md) for the full reference.

## Run through

**1. Onboard a battery**

You need a sandbox `site_id` and `asset_id` before you can send telemetry or receive dispatch.
Use whichever onboarding pathway you're building.

> [tab] Through your app
>
> Register a site and battery with
> [`POST /entities/site/onboard-site-and-asset`](./api-reference/onboard):
>
> ```bash theme={null}
> curl -sS -X POST https://api-sandbox.axle.energy/entities/site/onboard-site-and-asset \
>   -H "Authorization: Bearer $AXLE_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>         "site": {
>           "email": "example@example.com",
>           "mpan": "1234567890123",
>           "postcode": "SW1A 1AA",
>           "street_address": "10 Downing Street",
>           "gave_boundary_meter_consent_at": "2025-01-01T12:00:00Z"
>         },
>         "asset": {
>           "external_id": "battery-001",
>           "type": "battery",
>           "properties": {"power_kw": 5.0, "capacity_kwh": 13.5}
>         },
>         "dispatch_consent": {"dispatch_methods": ["vpp_limited_control"]}
>       }'
> ```
>
> The response carries the identifiers for the new site and asset:
>
> ```json theme={null}
> {
>   "site": {
>     "id": "9f2b7a13-4c8d-4e21-9a76-5d1c3b8e0f42",
>     "asset_ids": ["3c361164-5187-4b4b-8e8a-7b3f67c4d5a8"],
>     ...
>   },
>   "asset": {
>     "id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
>     "external_id": "battery-001",
>     "type": "battery",
>     "site_id": "9f2b7a13-4c8d-4e21-9a76-5d1c3b8e0f42",
>     ...
>   }
> }
> ```

> [tab] Through Axle's signup flow
>
> > [!NOTE]
> >
> > If we haven't set up OAuth2 with your platform yet, you can carry on with the
> > **Through your app** pathway instead. It gives you a sandbox `asset_id` for the
> > remaining steps in the same way.
>
> If we've set up OAuth2 with your platform in sandbox, sign up as a customer at
> [vpp-sandbox.axle.energy/app](https://vpp-sandbox.axle.energy/app). Pick your brand,
> sign in with a test account on your platform and confirm the battery.
>
> When signup finishes we send a
> [`vpp:asset:registered`](https://docs.axle.energy/workflows/webhooks#vpp%3Aasset%3Aregistered) webhook to your
> endpoint, carrying the `asset_id` alongside the device serial from your device-list API.

Keep the `asset_id`. You'll use it in the next two steps.

**2. Send telemetry**

Push readings for the battery to [`POST /data/readings`](./api-reference/telemetry). For an
event-only battery the minimum is state of charge and boundary power, both instantaneous, so
`start_timestamp` and `end_timestamp` match:

```bash theme={null}
curl -sS -X POST https://api-sandbox.axle.energy/data/readings \
  -H "Authorization: Bearer $AXLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "readings": [
          {
            "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
            "label": "battery_state_of_charge_pct",
            "value": 82.0,
            "start_timestamp": "2026-11-19T14:05:00Z",
            "end_timestamp": "2026-11-19T14:05:00Z"
          },
          {
            "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
            "label": "boundary_import_kw",
            "value": -1.4,
            "start_timestamp": "2026-11-19T14:05:00Z",
            "end_timestamp": "2026-11-19T14:05:00Z"
          }
        ]
      }'
```

We reply with a result for each reading:

```json theme={null}
{
  "responses": [
    {
      "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8",
      "label": "battery_state_of_charge_pct",
      "start_timestamp": "2026-11-19T14:05:00Z",
      "end_timestamp": "2026-11-19T14:05:00Z",
      "accepted": true
    },
    ...
  ]
}
```

A rejected reading comes back with `"accepted": false` and the reason in `error`. Once single
requests are accepted, leave it running on the 5-minute [cadence](https://docs.axle.energy/workflows/axle-vpp/integration.md#cadence)
you'll use in production.

**3. Receive events**

Call `POST /webhooks/test` and we'll deliver a dummy event to the endpoint you've registered,
through the same signing and retry machinery as a real one. Set `overrides.asset_id` to your
sandbox battery so the test drives your handler all the way through:

```bash theme={null}
curl -sS -X POST https://api-sandbox.axle.energy/webhooks/test \
  -H "Authorization: Bearer $AXLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "vpp:dispatch:requested",
        "overrides": {"asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8"}
      }'
```

We reply once the event is queued, and delivery follows within a few seconds. The event that
lands at your endpoint asks for a 1-hour discharge starting an hour from now:

```json theme={null}
{
  "id": "0198f0c3-4d5e-7f60-9b12-3c4d5e6f7081",
  "version": "v1.0.0",
  "event_type": "vpp:dispatch:requested",
  "created_at": "2026-11-19T14:10:02.512804Z",
  "payload": {
    "org": "your-org",
    "test": true,
    "event_id": "00000000-0000-0000-0000-000000000000",
    "issued_timestamp": "2026-11-19T14:10:02.512804Z",
    "start_time": "2026-11-19T15:10:02.512804Z",
    "end_time": "2026-11-19T16:10:02.512804Z",
    "assets": [
      { "asset_id": "3c361164-5187-4b4b-8e8a-7b3f67c4d5a8", "power_kw": -5.0 }
    ]
  }
}
```

Check that your endpoint:

* Verifies the signature with your signing key.
* Returns a `2xx` once it has durably accepted the event.
* Applies the target power to the battery, or recognises `"test": true` and skips it if you'd
  rather not move real hardware.

Then repeat with `"event_type": "vpp:site:opted_out"` to check your opt-out handling.

> [!NOTE]
>
> Unlike a real dispatch, a test window isn't aligned to a 30-minute boundary and its timestamps
> carry microseconds.

> [!TIP]
>
> Return a `5xx` to one test on purpose. The same event comes back thirty seconds later carrying
> the same `id`, which is how you check your deduplication.

If we refuse a test send, the reason is in `detail`. See
[When we refuse a test send](https://docs.axle.energy/workflows/webhooks.md#when-we-refuse-a-test-send).

When all three steps work, run through the webhook [quick checklist](https://docs.axle.energy/workflows/webhooks.md#quick-checklist)
and [get in touch](mailto:hello@axle.energy) to sign the integration off. We'll then set you up in
production.

## Next steps

> [card] [Integration](https://docs.axle.energy/workflows/axle-vpp/integration.md)
>
> The full integration contract for onboarding, telemetry, dispatch and opt-outs

> [card] [Webhooks](https://docs.axle.energy/workflows/webhooks.md)
>
> Envelope, signature verification, responses and retries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.