Permissions

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

PermissionAllows
machines:viewSee devices and read their data
machines:manageFull control of devices (includes view, edit, data ingestion)
machines:createCreate devices
machines:deleteDelete devices
machines:update_machines_groupMove devices between groups
machines:ingest_dataSend data with the HTTP Data ingestion
machines:generate_certsGenerate device certificates and pairing codes
machines:firmware_updateSend firmware updates
machines:firmware:manageManage device firmware
machines:config:manageRead and write device parameters
machines:config:configuration_level_N_read / _writeRead / write parameters of level N (1 to 5)
machines:commands:executeExecute device commands and actions
machines_groups:manageCreate and edit device groups and categories
machine_models:manageManage device models, firmware, commands, actions and notification rules
recipes:manageCreate, edit and delete recipes and send cookbooks
users:view / users:manageSee / manage users
roles:manageManage roles
sharing:manageShare devices
companies:view / companies:manageSee / manage sites and companies
plans:manageManage subscription plans
plans:machines:manageAssign plans to devices
machine_tokens:view / machine_tokens:manageSee / manage device tokens
dashboard_links:manageManage the home page links
widgets:manageManage 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.