Roles and Access Control
OTA-Pulse uses role-based access control with organizations as the tenancy boundary. Every resource belongs to exactly one organization. A user’s permissions are determined by their role in the membership record.
Roles
Four roles exist, in ascending order of privilege:
| Role | Description |
|---|---|
viewer | Read-only access. Can list devices, view metrics, and read deployment status. Cannot modify any resource. |
member | Can perform day-to-day operations: register devices, upload firmware, create and manage deployments (pause, cancel, retry, rollback). Cannot delete released firmware or manage users. |
owner | Can do everything a member can, plus delete released firmware that has no active deployments and use force: true on deployments to override min_version checks. |
admin | Full control within the organization, including managing users, changing roles, and all owner-level actions. Superusers (a server-level flag separate from org roles) bypass all org membership checks. |
Permissions matrix
| Action | viewer | member | owner | admin |
|---|---|---|---|---|
| View devices and metrics | yes | yes | yes | yes |
| Register / update devices | no | yes | yes | yes |
| Upload firmware and create deployments | no | yes | yes | yes |
| Pause / cancel / retry / rollback | no | yes | yes | yes |
| Delete released firmware | no | no | yes | yes |
| Force deploy (override min_version) | no | no | yes | yes |
| Manage users, signing keys, audit log | no | no | no | yes |
Organizations
All devices, firmware versions, deployments, API keys, and signing keys are scoped to one organization. A user can belong to more than one organization with a different role in each.
Organization tiers (free, pro, enterprise) set device and user limits.
Free organizations default to five devices and three users.
API keys
Devices and automated scripts authenticate with API keys — random tokens that
do not expire by default (an optional expires_at can be set). API keys carry
scopes that restrict what the key can do independent of the owning user’s
role:
| Scope | What it permits |
|---|---|
devices:write | Register devices and send heartbeats |
metrics:write | Push telemetry metrics |
coredumps:write | Upload crash coredumps |
ota:read | Check for and download OTA updates |
A key is linked to a user account and is scoped to one organization. Revoking
the key (revoked_at set) or deactivating it (is_active = false) immediately
invalidates it. An active key that has passed its expires_at timestamp is
also rejected at auth time.
Provisioning tokens are a special variant for first-boot device onboarding.
A single token is baked into a fleet image. When a device calls
POST /v1/provision, the server creates the device record and issues a
unique per-device API key. The token can be capped at a maximum device count
or restricted to specific hardware versions.
For user-authenticated endpoints, the server accepts a Bearer JWT in
the Authorization header. Devices and automated scripts should always use API
keys (see above) rather than user JWTs.