Authentication & API Keys

The API accepts two credential types. Use bearer tokens for interactive sessions and API keys for automation.

Bearer token (password / SSO)

curl -X POST https://api.totalview.energy/api/v1/auth/login/access-token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d "username=$EMAIL&password=$PASSWORD"

{ "access_token": "eyJhbGc…", "token_type": "bearer" }

Send on every request:

Authorization: Bearer eyJhbGc…

Single-sign-on (Google / Amazon Federate) is available via POST /auth/login/oidc and the Amazon authorize/callback endpoints — see the auth reference.

API keys (recommended for automation)

API keys don’t expire on a short clock and survive password changes — the right choice for scripts, CI, and integrations.

Create a key

curl -X POST https://api.totalview.energy/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "name": "CI pipeline", "expires_in_days": 365 }'

{
  "key_id": "…",
  "name": "CI pipeline",
  "key_prefix": "tv_live_abcde…",
  "raw_key": "tv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "is_active": true,
  "expires_at": "2027-05-15T00:00:00Z"
}

expires_in_days is optional (omit for no expiry). scopes may be supplied to narrow access.

Use a key

Send it in the X-API-Key header instead of Authorization:

curl https://api.totalview.energy/api/v1/projects \
  -H "X-API-Key: tv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

List and revoke

curl https://api.totalview.energy/api/v1/auth/api-keys -H "X-API-Key: $KEY"

curl -X DELETE https://api.totalview.energy/api/v1/auth/api-keys/$KEY_ID \
  -H "X-API-Key: $KEY"

GET returns metadata only (prefix, never the secret). DELETE deactivates the key immediately.

Next steps

Quickstart · Projects & Runs · full auth reference