Authentication

All requests are authenticated with a Bearer API key:

curl https://api.owner.dynvolt.com/v1/sites \
  -H "Authorization: Bearer dvk_live_a1b2c3d4e5f6_9f8e..."

Requests without a valid key receive 401 unauthorized.

Key format

dvk_live_<12 hex chars>_<64 hex chars>

• dvk_live_ — fixed prefix identifying a live DynVolt API key.
• <12 hex> — a public key ID. Safe to log; use it to tell keys apart.
• <64 hex> — the secret. Never log it, never send it anywhere except the Authorization header over HTTPS.

The stable prefix makes keys easy to find with secret scanners — treat any dvk_live_ string in a repo or log as a leak and rotate immediately.

Creating keys

Client admins create keys in the owner platform under Settings → Admin → API access. Each key is assigned a set of scopes at creation.

Scopes

Each token carries a set of scopes. Scopes map to module entitlements on your account — a scope can only be exercised if your account has the corresponding module enabled. There are 17 scopes in total; the full reference (what each grants, its module gate, and which are control scopes) is in Scopes & modules.

The read scopes span plant:read, weather:read, diagnostics:read, energy:read, curtailment:read, markets:read, alerts:read, reports:read (all under the basic_scada module), plus earnings:read, predictions:read, bess:read, and om:read (each behind its own module). The write scopes are alerts:write, reports:write, om:write, curtailment:write, and bess:write.

Calling an endpoint without the required scope returns 403 with code forbidden_scope; calling one whose module is not enabled for your account returns 403 with code forbidden_module. In both cases the error message names the missing scope or module — see Errors.

The key-creation screen only offers the scopes your plan includes, so a key can only be minted with scopes your account is entitled to. Grant each integration only the scopes it needs — a monitoring dashboard needs plant:read and energy:read, not om:write.

Control scopes

Two write scopes are control scopes — they command physical plant behaviour, not just records:

• curtailment:write — schedule, apply, or release curtailment.
• bess:write — the BESS dispatch-approval workflow (optimize / approve / reject / edit-hour).

Storing keys

• Keep keys in a secrets manager or environment variables — never in source control.
• Use one key per integration so you can revoke one consumer without breaking the others.
• The key ID (the 12-hex segment) is safe for logs and dashboards; the 64-hex secret is not.

Rotation and revocation

Keys can be rotated or revoked at any time from Settings → Admin → API access.

• Rotation issues a new secret; revocation disables the key entirely.
• Either change propagates in at most 60 seconds across the API. Until then, the old secret may still be accepted.
• For zero-downtime rotation: create a second key, switch your integration to it, verify traffic, then revoke the old one.

If you suspect a key has leaked, revoke it first and ask questions later — creating a replacement takes seconds.