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:writeandusers:write. automations:writewithoutdevices:command, or with a scopeddevices: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
idthat 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:readalso narrows the read thatdevices:writeordevices:commandimplies. - Type or driver.
typesmatches devices whose driver declares a standard type; a device with an untyped driver is reachable throughdriver_idsonly.
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.