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.
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
Section titled “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
Section titled “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.
Your plan sets the limits for an organization, such as devices, firmware assets, monitoring data points and concurrent Remote SSH sessions. See Pricing and limits for the current tiers and caps.
API keys
Section titled “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 |
The metrics:read, devices:read, coredumps:read, firmware:read and
firmware:write scopes are retired: no endpoint ever checked them, so they
never granted any access. The metrics, devices, coredumps, firmware and
deployments management endpoints require a signed-in user session, not an API
key, so a key cannot be used to automate them. Creating an API key or a
provisioning token with a retired scope is rejected (HTTP 422). Existing keys
that still carry one keep working for their other scopes.
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.