Skip to main content

Authentication

Every request to the Evinor API is authenticated with an API key sent as a bearer token. There are no unauthenticated endpoints.

Key format​

An Evinor API key looks like this:

evnr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXYYYYYY
  • It always begins with the fixed prefix evnr_live_.
  • The prefix is followed by a 30-character random secret and a 6-character checksum, all drawn from the base62 alphabet (0-9A-Za-z) — 46 characters in total.
  • The trailing checksum lets a client or server reject an obviously malformed key without a lookup, so a typo'd or truncated key fails fast.

Evinor stores only a one-way hash of the key, never the raw value. The raw key is shown a single time, at creation (see Getting Started).

Sending the key​

Put the key in the Authorization header using the Bearer scheme:

curl https://api.evinor.ai/v1/sensors \
  -H "Authorization: Bearer evnr_live_your_key_here"

A missing, malformed, unknown, or revoked key is rejected with a 401 and the invalid-api-key problem type. For security, Evinor returns the same 401 whether a key never existed or was later revoked — the response never reveals which.

Scopes​

Each key carries one or more scopes that determine which endpoints it may call:

ScopeGrants
SENSORS_READList and read sensors.
SENSORS_WRITECreate, update, enable, disable, delete, and rotate secrets.

Calling an endpoint your key isn't scoped for returns a 403 with the missing-scope problem type, naming the scope(s) you need. Scopes are fixed when a key is created; to change them, create a new key with the scopes you want and revoke the old one.

Rotating a key​

Because scopes are immutable and the raw value is shown only once, "rotating" a key means replacing it. Rotate on a schedule, and immediately if you suspect a key was exposed. Do it without downtime by overlapping the old and new keys:

  1. Create a new key with the same scopes.
  2. Migrate every caller to the new key (deploy it to your environments).
  3. Verify traffic is flowing on the new key.
  4. Revoke the old key from Settings → API keys once nothing uses it.

Because both keys are valid during steps 1–3, there is no gap in service. After revocation, any lingering caller using the old key immediately receives a 401.

Key hygiene​

  • Never commit keys to source control. Load them from environment variables or a secrets manager. Keys accidentally pushed to a public repository may be detected by automated secret scanners and should be treated as compromised — revoke and replace them.
  • Scope minimally. Grant a key only the scopes it needs; use a read-only key for reporting or dashboards.
  • Use one key per integration. Separate keys let you revoke a single integration without disrupting the others, and make audit trails clearer.
  • Rotate periodically, and always after a suspected exposure.