How permissions work
CHeKT permissions are granular, additive, and reversible. Each permission grants access to a specific verb (read or write) on a specific resource family. Apps request the scopes they need at creation; the dealer admin approves the set as a whole.
You can later tighten permissions silently. Widening requires the dealer admin to re-approve.
- Scope
- A named permission like devices:read. Each scope is independent — you can grant any combination.
- Read
- Lists, gets, paginates. Never side-effects. Safe to grant broadly.
- Write
- Mutates state. Acknowledge, dispatch, arm, disarm. Grant only when needed.
- Domain split
- We split related actions across multiple scopes when the impact differs — alarms:write is separate from events:write because dispatch has cost.
All scopes
The complete permission catalog, grouped by resource family. Each scope lists the endpoints it unlocks and (where relevant) the webhook events it gates.
Devices
Cameras, bridges, sensors, and any other hardware reporting to CHeKT.
devices:readreadRead device metadata, status, firmware, signal strength, and configuration.
Unlocks endpoints
GET /v1/devicesGET /v1/devices/{id}GET /v1/devices/{id}/snapshots
Required to receive events
device.onlinedevice.offlinedevice.firmware_updated
devices:writewriteUpdate device labels, groupings, and configuration. Trigger snapshots.
Unlocks endpoints
PATCH /v1/devices/{id}POST /v1/devices/{id}/snapshot
Events & Alarms
The signal stream that drives every monitoring decision.
events:readreadRead events and alarm history across the dealer.
Unlocks endpoints
GET /v1/eventsGET /v1/alarmsGET /v1/alarms/{id}
Required to receive events
alarm.createdalarm.resolvedverification.requested
events:writewriteAcknowledge, escalate, annotate, or close alarms. Cannot delete history.
Unlocks endpoints
POST /v1/alarms/{id}/acknowledgePOST /v1/alarms/{id}/escalatePOST /v1/alarms/{id}/annotate
alarms:writewriteDispatch responders. Distinct from events:write because dispatching has cost implications.
Unlocks endpoints
POST /v1/alarms/{id}/dispatch
snapshots:readreadRead snapshot URLs and metadata tied to events.
Unlocks endpoints
GET /v1/snapshots/{id}GET /v1/devices/{id}/snapshots
Required to receive events
snapshot.created
Sites & Partitions
Physical and logical grouping holding your devices.
sites:readreadRead site, partition, and zone data.
Unlocks endpoints
GET /v1/sitesGET /v1/sites/{id}/partitionsGET /v1/sites/{id}/zones
Required to receive events
partition.armedpartition.disarmed
sites:writewriteArm, disarm, bypass zones, and update partition configuration.
Unlocks endpoints
POST /v1/partitions/{id}/armPOST /v1/partitions/{id}/disarm
Operators
Operator accounts at the dealer level. Useful for audit + roster apps.
operators:readreadRead operator roster, roles, and audit log.
Unlocks endpoints
GET /v1/operatorsGET /v1/operators/{id}/audit
Webhooks
Manage the webhook delivery configuration for this app from code.
webhooks:readreadRead the current webhook subscription and delivery log.
Unlocks endpoints
GET /v1/webhook_endpoints/{id}GET /v1/webhook_endpoints/{id}/deliveries
webhooks:writewriteUpdate the URL, signing secret, or event subscriptions for this app's webhook.
Unlocks endpoints
PATCH /v1/webhook_endpoints/{id}
Common permission sets
Starting points for typical app shapes. Pick the closest one and trim or expand from there.
AI verification app
Reads alarms + snapshots, writes verification verdicts back.
events:readsnapshots:readevents:write
Reporting / dashboard
Read-only across the platform.
events:readdevices:readsites:readoperators:read
Auto-dispatcher
Routes high-confidence alarms to a guard service automatically.
events:readalarms:write
Audit + compliance
Pulls operator action history for regulators.
operators:readevents:readsites:read