Roles and permissions that decide what an API caller can do.
What a user or API integration can do through the API depends on its roles, exactly as in the web platform. The API returns only the organizations, devices and data the caller can see, and answers 403 to operations it is not allowed to perform.
Where roles are assigned
- Organization role: applies to the whole organization. Organization administrators can do everything, including managing API integrations.
- Role on a device group: applies to the devices of that group and of its sub-groups. Permissions are cumulative: a role on a parent group cannot be restricted by a role on a child group, and the broadest permission wins. See Roles.
- Shared device: a device shared directly with a user, with a role (Device users, Device tokens).
API integrations have no organization role: give them a role on the device groups they need.
Permissions
| Permission | Allows |
|---|---|
machines:view | See devices and read their data |
machines:manage | Full control of devices (includes view, edit, data ingestion) |
machines:create | Create devices |
machines:delete | Delete devices |
machines:update_machines_group | Move devices between groups |
machines:ingest_data | Send data with the HTTP Data ingestion |
machines:generate_certs | Generate device certificates and pairing codes |
machines:firmware_update | Send firmware updates |
machines:firmware:manage | Manage device firmware |
machines:config:manage | Read and write device parameters |
machines:config:configuration_level_N_read / _write | Read / write parameters of level N (1 to 5) |
machines:commands:execute | Execute device commands and actions |
machines_groups:manage | Create and edit device groups and categories |
machine_models:manage | Manage device models, firmware, commands, actions and notification rules |
recipes:manage | Create, edit and delete recipes and send cookbooks |
users:view / users:manage | See / manage users |
roles:manage | Manage roles |
sharing:manage | Share devices |
companies:view / companies:manage | See / manage sites and companies |
plans:manage | Manage subscription plans |
plans:machines:manage | Assign plans to devices |
machine_tokens:view / machine_tokens:manage | See / manage device tokens |
dashboard_links:manage | Manage the home page links |
widgets:manage | Manage dashboards and widgets |
Visibility of device models
The device models a user can see are those of the devices they have the view permission on, plus all the organization's models if they have machine_models:manage.
