Use this file to discover all available pages before exploring further.
Two surfaces authenticate against Amps. Your application authenticates to the Amps API with an API key. Your end users connect their devices through the Auth Journey, a hosted flow that collects OEM credentials and registers devices against your account.
Every API request carries an API key in the x-api-key header. Each key is validated on every request; metadata stored on the key drives environment routing and customer scoping.
Each key carries a customerId and environment baked into its metadata at creation time. Environment is one of sandbox or live, fixed at issuance. A sandbox key never accesses live data, a live key never accesses sandbox data, and the environment cannot be overridden via request parameters. The split is absolute.
Prefix
Environment
amps_sk_test_*
Sandbox
amps_sk_live_*
Live
Manage keys from the dashboard. The public API does not expose key creation or revocation.
Key is unrecognised, malformed, revoked, or soft-deleted.
EXPIRED_TOKEN
401
Key has passed its expiry.
RATE_LIMIT_EXCEEDED
401
Key has exceeded its rate ceiling.
INSUFFICIENT_PERMISSIONS
403
Key lacks the permission for the requested operation.
LIVE_ACCESS_DISABLED
403
Live key used by a customer not enabled for live access.
A revoked key is soft-deleted: subsequent requests return 401 with the revocation message in error.message, the audit trail persists, and the key body never executes again.See the error envelope for the full response shape.
Sandbox runs the whole stack against simulated devices, on the same code paths live uses. Build the integration, ship to staging, run a full test pass, all without touching a real OEM credential. The first OEM credential the customer’s end users hand over should be after the integration is finished, not during.Sandbox is on by default for every new account. Simulated devices return deterministic data with realistic timing and the same response shapes as live. No OEM credentials are needed. Every code path the live environment uses runs in sandbox too: the same auth guards, the same cache, the same async write path, the same webhook delivery. The only divergence is at the OEM-call layer.Sandbox access needs no enablement flag. A live API key against a customer not yet enabled for live returns 403 LIVE_ACCESS_DISABLED. Sandbox keys skip that check.Sandbox shows every device the platform supports. Live shows the OEMs your Customer App is configured for, filtered to the tiers you are entitled to. See capabilities for the availability tier model.
Sandbox devices return deterministic data driven by UTC time-of-day, so the same call at the same wall-clock instant returns the same shape across runs. Useful when you’re writing fixtures or asserting against expected values.
Device type
Morning (06-09 UTC)
Midday (09-15 UTC)
Evening (15-21 UTC)
Night (21-06 UTC)
Vehicles
Plugged in, 80-95%
Unplugged, level decreasing
May plug in for overnight
Plugged in, charging
Batteries
Discharging for morning load
Charging from solar
Discharging for peak usage
Idle or slow charging
Solar inverters
Ramping up
Peak production
Declining
No production
HVAC and EV charger sandbox behaviour follows the device type’s typical residential pattern; see the cookbook for a worked example.
Live access requires explicit enablement on your account. Until that flag is set, every live API key returns 403. Once enabled, live keys access live data and reach real OEM hardware.
Sandbox key: skip live check. Pass.Live key: check live-enabled. Pass or 403.
This is the boundary between development and production. A sandbox key is safe to embed during integration; pushing one to production is harmless because it cannot reach live data. A live key only operates after a deliberate enablement step.
Sandbox and live data are stored in fully isolated schemas. Customer accounts are shared across the two; devices, credentials, actions, and schedules are not. Queries route to the correct schema based on the environment your API key carries.
Beyond the API key check, every device-scoped request verifies the device belongs to your account in the request’s environment.
Code
HTTP
Trigger
DEVICE_NOT_FOUND
404
Device does not exist, or exists but is not linked to your account in this environment.
The 404 is deliberate. Returning 403 would leak the existence of devices belonging to other customers. Either you can see it, or it does not exist as far as you are concerned.
End users connect their OEM accounts through the Auth Journey, a hosted flow you embed in your app via a Plaid Link-style hand-off. You pass appId and a userId (your own end-user identifier) to the URL, the journey walks the user through device connection, and redirects back to your redirectUrl on success.The step sequence: device type selection, OEM selection (filtered by your Customer App’s supported OEMs), auth method choice (where the OEM offers more than one), credential or API-key entry, MFA verification (if the OEM requires it), device selection, consent collection, success and redirect.Browser back navigation is disabled after the credentials step. Once credentials are in flight to the OEM, allowing back would leave the session inconsistent. Credentials never touch browser storage; they live only in component state. Short-lived signed tokens carry context between steps and prevent tampering.When credentials expire (OEM revokes a session, the user changes their password), Amps emits device.disconnected with a reconnectionUrl. The user follows it, the journey runs in reconnection mode skipping device-type, OEM, and device selection, the credential record refreshes, and device.reconnected fires. See webhooks.Each Customer App declares redirectUrl, reconnectRedirectUrl, logoUrl, appName, and a list of supported OEMs. Manage Customer Apps from the dashboard.
Devices that exceed an allowance are flagged as overage and access is restricted. Overage is preferable to hard-rejecting at registration time: it lets trial flows continue without losing data, and lowering an allowance never silently deletes devices.
A small number of routes are public and bypass authentication. The OpenAPI spec at /openapi.json and a few health endpoints fall in this category. The full list is in the API reference; everything else requires a valid key.
The same code paths, the same cache rules, the same response shapes. Sandbox uses simulated devices that return deterministic data with realistic timing; live talks to real OEM hardware. Every code path the live environment exercises is exercised in sandbox: the same auth guards, the same cache layer, the same async write path, the same webhook delivery. The only divergence is at the OEM-call layer. Sandbox keys never reach live data; live keys never reach sandbox data.
What happens if I send a sandbox key to the live host?
Both environments live behind the same host. The split is enforced at the API key, not the host: a key prefixed amps_sk_test_* always routes to sandbox, a key prefixed amps_sk_live_* always routes to live. The environment is fixed at issuance and stamped into the key’s metadata. Callers cannot override it via request parameters. A live key against a customer not yet enabled for live returns 403 LIVE_ACCESS_DISABLED.
Every key carries customerId baked into its metadata at creation time. The customer record is shared across environments; device records and everything below are isolated by environment. Beyond the API key check, every device-scoped request verifies the device belongs to the authenticated customer. A device that exists but is not linked to this customer returns 404, not 403, to avoid leaking the existence of devices owned by other customers.
A hosted flow embedded in your application via Plaid Link-style hand-off. End users connect their OEM accounts through it; the journey walks them through device-type selection, OEM selection, credential entry, MFA, device selection, consent, and registration. Credentials never touch browser storage; they exist only in component state. Short-lived signed tokens carry context between steps. On success, the journey redirects back to your redirectUrl and the platform fires a device.connected webhook.
Two caps exist on every customer: a global cap (total devices across all OEMs) and a per-OEM cap. Devices that exceed an allowance are flagged as overage and access is restricted. Overage is preferable to a hard rejection at registration time: it lets trial flows continue without losing data, and reducing an allowance does not silently delete devices. Allowances are managed from the dashboard.
