Skip to content

Roles and Permissions

Access to Gridone is described by four concepts.

Concept Definition
User An account that authenticates against Gridone: a person or an application. Every user holds exactly one role. See Users and Authentication.
Role A named set of permissions, identified by a short id such as operator. Gridone ships three built-in roles and lets administrators define custom ones.
Permission The right to act on one kind of resource at one level, such as devices:read. Permissions are held by roles, never by users directly.
Scope An optional restriction that narrows a device permission down to specific devices and attributes. See Scopes.

Every operation requires one permission. On each request Gridone resolves the caller's role to its permissions and refuses the operation when the required one is missing. There is no per-user override: to change what a user can do, change their role or edit the role itself.


Permissions

A permission is written <resource>:<level>.

Level Grants
read Listing and reading the resource
write Creating, updating and deleting it

Resources are the kinds of things Gridone manages. Reading never implies writing, but writing implies reading: a role holding devices:write also reads devices, whether or not it lists devices:read. The one write that implies nothing is notifications:write, since reading your own notifications needs no permission.

Resource Covers Levels
users User accounts, blocking, service keys, app registration read, write
roles Built-in and custom roles read, write
devices Devices, their live values, faults and presentations read, write, plus device specifics
assets Zones and assets read, write
transports Networks and discovery read, write
drivers Drivers read, write
timeseries Recorded device history read only: history is written by Gridone itself
automations Automations and their executions read, write
operating_rules Site operating rules guarding device writes read, write
notifications Dispatching a notification to other users write only: reading and dismissing your own needs no permission
dashboards Dashboards read, write
synoptics Synoptics read, write
journal The site-wide journal of business events read only, which also exports the entries: they are written by Gridone itself. Reserved for admin

Device specifics

Devices are the one resource where "write" is two different things: configuring the device, and operating the equipment behind it. Gridone keeps them apart so that a role can turn a thermostat up without being able to delete it.

Permission Grants
devices:write Configuring devices: creating, updating and deleting them, managing their tags and views
devices:command Operating devices: sending a command to writable attributes, alone, in batch or through a template
devices:logs:read Reading the communication log of an attribute, for troubleshooting

devices:command implies devices:read, like any write: a role that operates equipment sees the devices it operates.

Always allowed

Some actions need no permission beyond being signed in: reading your own profile, changing your own password, reading or dismissing your own notifications, and listing users as an id and a display name. That basic listing is what lets any role show who sent a command or pick notification recipients; the full profiles, with username and role, still need users:read.


Built-in roles

Three roles are defined in code and exist on every instance.

Role Intended for
admin Administrators. Holds every permission, including user and role management.
operator Integrators and building operators. Full control and configuration of the building, no user management.
viewer Anyone who needs to look but not touch. Read-only access to the building.
Permission admin operator viewer
users:read ✓
users:write ✓
roles:read ✓ ✓ ✓
roles:write ✓
devices:read ✓ ✓ ✓
devices:write ✓ ✓
devices:command ✓ ✓
devices:logs:read ✓
assets:read ✓ ✓ ✓
assets:write ✓ ✓
transports:read ✓ ✓ ✓
transports:write ✓ ✓
drivers:read ✓ ✓ ✓
drivers:write ✓ ✓
timeseries:read ✓ ✓ ✓
automations:read ✓ ✓ ✓
automations:write ✓
operating_rules:read ✓ ✓ ✓
operating_rules:write ✓
notifications:write ✓
dashboards:read ✓ ✓ ✓
dashboards:write ✓ ✓
synoptics:read ✓ ✓ ✓
synoptics:write ✓ ✓
journal:read ✓

Built-in roles cannot be edited or deleted. Because admin always holds every permission, an instance cannot lock itself out by misconfiguring a role.

operator is the default role of a new user.


Custom roles

An administrator can define additional roles when the built-in ones do not fit. A custom role is a document with five fields:

Field Description
id A short slug, unique across built-in and custom roles. It is what a user's role field refers to, and it cannot be changed after creation.
name Display name
description Free text, shown in the user form
permissions Any subset of the permissions above
scopes Optional. Narrows devices:read and devices:command to specific devices and attributes, see Scopes

Custom roles are managed through the API and require the roles:write permission. That permission, like users:write and journal:read, is reserved for the built-in admin role: a custom role cannot hold any of them. Assigning a role to a user, in turn, requires holding every permission of that role, counting the ones the caller's role implies. Together the two rules mean no role can hand out more than it has, whether by editing roles or by editing users.

Rules:

  • A permission outside the vocabulary is rejected, and so are roles:write and users:write.
  • automations:write without devices:command, or with a scoped devices:command, is rejected. See below.
  • A scope on a permission the role does not hold, on a permission that is not scopable, or with an empty list is rejected.
  • An id that already exists is rejected.
  • A role assigned to at least one user cannot be deleted. Reassign the users first.
  • Changing a role's permissions takes effect on the next request of every user holding it. No re-login is needed.

Automations run as the system. A role that writes automations commands every device, so it must hold devices:command, unscoped.

Example: a thermostat operator

An occupant-facing role should read the building and adjust comfort settings, but never configure a device or touch accounts:

{
  "id": "thermostat_operator",
  "name": "Thermostat operator",
  "description": "Reads the building and adjusts comfort settings.",
  "permissions": ["devices:read", "devices:command", "timeseries:read", "dashboards:read"]
}

Without devices:write, a user with this role cannot create, edit or delete a device. It still sees every device and reaches every writable attribute, thermostat or not: narrowing that is what scopes are for.


Scopes

A permission is all-or-nothing: devices:read shows a role every attribute of every device, and devices:command lets it command every writable one. A scope narrows one of these two permissions to a subset of devices and attributes.

Scopes are keyed by the permission they narrow. Each scope has two parts: which devices it reaches, selected by standard type or by driver, and optionally which attributes of those devices. A part left out is no restriction. A role that reads thermostats, and only their comfort values:

{
  "id": "comfort_reader",
  "name": "Comfort reader",
  "description": "Sees the temperature and setpoint of every thermostat, nothing else.",
  "permissions": ["devices:read", "timeseries:read", "dashboards:read"],
  "scopes": {
    "devices:read": [
      { "devices": { "types": ["thermostat"] }, "attributes": ["temperature", "temperature_setpoint"] }
    ]
  }
}

How a scope is read:

  • Inside a scope, parts intersect. A device must match every part that is set: here it must be a thermostat, and only the two listed attributes are visible on it. {} is a scope with no restriction.
  • Across scopes, matches union. Listing two scopes under the same permission reaches what either of them reaches. There are no deny entries and no ordering.
  • A scope never exceeds its permission. The key must be one of the role's permissions, or one they imply. A permission without a scope keeps its full reach, and a scope on devices:read also narrows the read that devices:write or devices:command implies.
  • Type or driver. types matches devices whose driver declares a standard type; a device with an untyped driver is reachable through driver_ids only.

What a scoped role is served follows one rule: what it cannot read does not exist for it. A hidden attribute is absent from the device, its history and the live feed. A device with no readable attribute is absent from lists, answers "not found" when addressed directly, and is left out of attribute coverage, faults and communication logs. Two pieces of metadata stay visible because Gridone computes them over the whole device: whether a device is faulty, and the fact that a device exists when a command targets it.

The live feed applies the role as it was when the connection opened; a connection lasts no longer than the access token behind it, so an edit to the role reaches the feed at the next reconnection.

Roles without scopes, built-in or custom, are unaffected: scopes only narrow, they never grant.

Commanding through a scope

A scope on devices:command narrows what the role may command. A front desk role that sees the thermostats and changes their comfort settings, nothing technical:

{
  "id": "receptionist",
  "name": "Receptionist",
  "description": "Front desk: comfort settings on thermostats, nothing technical.",
  "permissions": ["devices:read", "devices:command", "timeseries:read", "dashboards:read"],
  "scopes": {
    "devices:read": [
      { "devices": { "types": ["thermostat"] } }
    ],
    "devices:command": [
      { "devices": { "types": ["thermostat"] }, "attributes": ["temperature_setpoint", "hvac_mode", "fan_speed"] }
    ]
  }
}

An attribute the role reads but may not command is served as read-only: its read_write_modes loses write, exactly as if its driver could not write it. A write-only attribute it may not command would offer nothing, so it is hidden like an attribute the role cannot read. A command on it alone is refused as "forbidden". A command on several devices, a grouped command and its preview, a command on an asset and the run of a command template are refused as "forbidden" when their target reaches a device the role may not command: nothing is sent, not even to the devices it may command. Running a template someone else saved is checked the same way, against the role of whoever runs it. Saving a template is stricter: automations run it later, on every device its target reaches, so a role may not save or edit a template whose target reaches a device it may not command.

The read that devices:command implies follows its scope. An attribute a devices:command scope reaches is readable even when the devices:read scope does not list it, and a role holding a scoped devices:command without devices:read or devices:write reads exactly what it may command.