Users and roles

This page is for administrators. It explains what each role allows, how the first account comes about, and how the Users page works. The role model is also summarized in Security.

The four roles

A user has one role. Each role can do everything the one before it can:

Role	Adds
viewer	Read everything below /api/v1 except users and the audit log, subscribe and replay on /sync, and change their own preferences
operator	Write to tags: tag.write on /sync and POST .../tags/{id}/write
engineer	Configure tags, tag types (UDTs), screens and start screens, and call module endpoints that change something, which includes driver connections and browsing them
admin	Manage users, read the audit log, and set the project directory

The dashboard shows the roles as Viewer, Operator, Engineer and Administrator, each with a one-line summary:

• Viewer: "Can watch tags, alarms and screens, and change nothing."
• Operator: "Can also write to tags and acknowledge alarms."
• Engineer: "Can also configure tags, types, screens and connections."
• Administrator: "Can also manage users, API keys and gateway settings."

Module endpoints have no say in their policy: a GET needs viewer and any other method needs engineer, unless the module marks an endpoint as one that writes tag values, which lets operators call it.

What roles do not do

• Roles are not scoped to tags. An operator can write to every tag; a viewer can read every tag.
• Screens are not protected by role. The dashboard only filters menus and hides commands and write widgets from viewers as a courtesy. The enforcement is the role check on each API route and on /sync.
• There is no per-screen, per-folder or per-device permission.

The first account

The first account on a gateway is its administrator, however it is created: through the setup screen the dashboard shows while GET /api/v1/admin/setup answers {"needsSetup": true}, through POST /api/auth/sign-up/email, or through POST /api/v1/admin/users without a session. Once one user exists, public sign-up answers 403 and creating users needs an admin session.

note

Upgrading a gateway from before roles existed makes every existing user an admin, so nobody is locked out, and signs everybody out once. Review the roles afterwards.

The Users page

Open the Gateway area in the rail, then Security, then Users. The page lists every account with its Name, Email, Role and Created date; your own row is marked You. Selecting a row opens a panel beside the list. Anyone who is not an administrator sees "Only administrators can manage users" instead.

Creating a user

1. Click Add user.
2. Fill in Name, Email and Password. The form warns when the password is shorter than 8 characters, but does not refuse it.
3. Choose a Role. The default is Viewer.
4. Click Create user. The new account can sign in at once with that email and password.

Give the password to the person through a channel you trust. There is no invitation email.

Changing a role

1. Select the user.
2. Change Role and click Save role (or Revert).

The new role applies to the user's next request. The role is read from the database on every request rather than trusted from the session cookie. An open /sync socket checks the stored role on every write, and closes within 30 seconds if the session ends or no longer holds a known role.

Deleting a user

Select the user and click Delete user under Remove access, then confirm. Deleting an account ends their open sessions and removes their saved preferences. Their rows in the audit log keep their user id, so the record outlives the account.

The dashboard does not let you delete the account you are signed in with; another administrator has to do it.

The last administrator

A gateway must keep at least one admin. Demoting or deleting the only administrator answers 409 with "A gateway must keep at least one admin." The dashboard disables the role select and the delete button for that account and says to make someone else an administrator first. The check is part of the same statement that writes, so two admins demoting each other at the same moment cannot both succeed.

Passwords

Passwords are hashed before they are stored. The gateway has no route to change a password and no password reset: to give someone a new password, delete the account and create it again. Signing in with an outside identity provider does not use a gateway password at all; see Identity providers.

Limits

• One role per user; no groups, no per-tag or per-screen permissions.
• No password change, no password reset, no email verification flow.
• The name field is free text; the email must look like name@domain.

API

All user routes need the admin role except the two bootstrap routes. The full reference is in Admin API and Auth API.

Route	Purpose
GET /api/v1/admin/setup	Anonymous; {needsSetup} is true while no user exists
GET /api/v1/admin/users	List users: id, name, email, emailVerified, role, createdAt
POST /api/v1/admin/users	Create {email, name, password, role?}; role defaults to viewer. Anonymous only for the very first user
PATCH /api/v1/admin/users/{id}	Change the role: {role}. 409 when it would leave no admin
DELETE /api/v1/admin/users/{id}	Delete; 409 for the last admin
POST /api/auth/sign-in/email	Sign in with {email, password, rememberMe?}
POST /api/auth/sign-up/email	First account only; 403 "Public sign-up is disabled" afterwards
GET /api/auth/get-session	The current session and user, or null
POST /api/auth/sign-out	End the session

A role value must be one of viewer, operator, engineer, admin; anything else answers 400.