Create and manage API keys

Use Authorization: Bearer $ERGOPS_API_KEY. Test and Live keys are independent machine identities bound to exactly one organization. They are not organization members and do not inherit a human role.

Test keys begin with ergops_test_; Live keys begin with ergops_live_. Never place either in browser code, source control, screenshots or support messages. Store them in a server-side secret manager or protected environment variable.

Raw keys are generated with cryptographically secure randomness, shown once and retained only as a SHA-256 digest of the high-entropy secret. Rotate keys by creating a replacement and optionally allowing a short overlap before the old key expires. Revocation takes effect on the next request.

Currently issued scopes are least-privilege: emissions:calculate, emissions:read, customers:read, and customer-analytics:read. Report and webhook-read scopes are intentionally not issued until matching public endpoints exist.

Lifecycle#

• Create: the raw key is displayed exactly once.
• Rotate: issue a replacement; optional overlap consumes contract key capacity.
• Revoke: the next request with the old key fails.
• Expire: an expired key returns API_KEY_EXPIRED.