Scopes

A key is granted scopes when it is created. Each endpoint requires exactly one scope, and a key that lacks it is refused with 403 insufficient_scope, naming the scope in required_scope.

Scope names follow resource:verb. v1 is read-only, so every scope is a :read.

Scope	Grants
devices:read	GET /devices, GET /devices/{device_id}
telemetry:read	GET /devices/{device_id}/telemetry
alerts:read	GET /alerts, GET /alerts/{alert_id}
account:read	GET /account

The scope each operation requires is also declared on the operation itself in the API reference.

Choosing scopes

Grant the least a given integration needs, and prefer one key per integration over one key for everything: a key that only reads telemetry cannot be used to enumerate alerts if it leaks, and revoking it does not take anything else down.

A scope name outside the declared set cannot be granted. If a later version retires a scope, keys that hold it simply stop being granted anything by it — a retired scope never widens into “everything”.