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.
EVENTS_READSearch the historical event corpus. Billed — see Searching events.
REPORTS_READList the event types you can report, your reporting grants, and your filed reports; search entities. See Reporting events.
REPORTS_WRITEFile first-hand reports, published under the key owner's name (POST /v1/reports). Not billed.
BEATS_READList and read beats, and read their entries. Not billed. See Beats.
BEATS_WRITECreate, replace, delete, enable, disable, and resume beats, and set their spend caps. A beat spends credits as it records entries.

An endpoint lists every scope it requires, and a key must hold all of them. A key that files reports needs REPORTS_READ as well as REPORTS_WRITE: without it the key cannot look up event types or entity ids, so it cannot build a valid report. The key dialog ticks REPORTS_READ for you when you tick REPORTS_WRITE. Likewise, a key with BEATS_WRITE should hold BEATS_READ, so it can read back the beats it writes; the dialog ticks it for you.

You can only give a key a scope your account is entitled to use. REPORTS_WRITE is available only on accounts with structured reporting or entity reporting. Evinor also re-checks the entitlement on every report, so a key whose owner has since lost it gets 403 not-entitled rather than missing-scope.

A key holding EVENTS_READ can spend credits: every search it executes is charged to the account's balance, and a request made with an exhausted balance returns a 402 insufficient-credits. Grant it only to integrations that need to search.

A key holding BEATS_WRITE can also lead to spending: a beat it creates spends credits on its own as it records entries, up to the beat's monthly spend cap (see Beats). Reading beats and their entries is not charged.

The same key, presented the same way, is how an agent authenticates to the MCP server. There, a key sees only the tools its scopes allow: EVENTS_READ unlocks the event-search tools, REPORTS_READ the event-type and reporting-grant tools, REPORTS_WRITE the report-submission tool, BEATS_READ the beat read tools, and BEATS_WRITE the beat-creation tool. The sensor scopes unlock no tools.

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.