Roles & Permissions

Consystence authorisation is built on two independent dimensions:

1. A membership role — your authority over the tenant (who may administer the organisation). This is live today and is exactly owner, admin, or member.
2. A set of access groups — your capability to view and control sites and equipment. This is the finer-grained model, and it is forthcoming (see Access groups).

The two are orthogonal. A tenant admin may hold no site-control access; a member may hold broad control access. Authority is the power to administer the organisation and grant access; access is the power to operate. Conflating them is the defect the current model fixes — the older five-role set (owner/admin/engineer/operator/viewer) leaked operational capability into the authority field and has been removed.

On a site server a third, separate plane applies today: site roles, which govern site functions for people who sign in to that server by email and PIN — see Site roles on a site server.

flowchart LR
  M[Tenant member] --> R[Membership role<br/>owner · admin · member]
  M --> G[Access groups<br/>forthcoming]
  R --> A[Tenant administration]
  G --> C[View / control capability]

Membership roles

Every member of an organisation holds exactly one membership role.

Role	Tenant administration	Manages members
owner	Full	Manages everyone. The irreducible root of the organisation.
admin	Full — manage members, domains, licences and sites	Manages members.
member	None	None. (Control access is a separate dimension — see Who may operate a site.)

The roles that confer tenant-administration authority are owner and admin. Administrative surfaces (managing the tenant’s members, sites, edges, credentials and configuration) are gated on these two roles; a member is denied.

Note

A membership role is not read from a bearer token. For cloud sessions it is resolved server-side from your organisation membership, keyed by your stable Entra oid — an org_role claim presented on a token is not trusted for authority. See Authentication for how each credential type carries (or omits) identity.

owner is the irreducible root

owner is a real authority tier above admin, not a synonym:

• An organisation always has an owner: the owner cannot be removed, and ownership moves by transfer. Today each organisation has a single owner; a sole owner who loses access is recovered through support (see below).
• Owners and admins are managed on the account console, which never removes an organisation’s owner, and the cell mirrors that set.

Target model — multiple owners forthcoming

Multiple owners, granted and revoked by an owner, are the ratified target model, with delivery forthcoming. Today each organisation has a single owner, and the cell’s guard is last-admin protection — an org must retain at least one owner-or-admin.

Last-admin and owner protection

The platform refuses changes that would leave an organisation unadministerable. The cell’s guard prevents removing the last admin-authority member, and the account console never removes an organisation’s owner. A blocked “remove the last admin” attempt is rejected (HTTP 409) and recorded in the operational journal with its refusal (see Auditing).

Caution

Owner-protection introduces a recovery edge case: a locked-out sole owner cannot be recovered through normal organisation administration. Recovery of a locked-out sole owner is handled through a support request. Owner-initiated self-service transfer ownership and delete organisation are built: an ownership transfer atomically carries the tenant owner role with it, and deleting an organisation requires that it hold no tenants and no active billing, confirmed by typing the organisation’s name. (Deleting an individual tenant is separate and also shipped: an owner drives it from the account console with slug-typed confirmation — see tenant provisioning.)

Access groups (forthcoming)

The finer-grained, orthogonal access dimension is being designed as a foundation-first programme and is not yet available. When it lands it will provide:

• Per-capability authorisation on the control surface — whether a given access group may invoke a given capability on a given device instance, defined in standard-library templates (for example, a pump template granting operator start/stop and engineer PID tuning), overridable per instance, and enforced at runtime.
• Access groups — collections of capability grants (illustrative defaults such as manager, engineer, operator, observer, plus custom groups). Site-authored and replicated per the org/site model.

Not yet generally available

Access groups and per-capability authorisation are forthcoming. Until they ship, control access is governed by membership, as described below, not by groups.

Site roles on a site server

Site roles are a separate authorisation plane from org membership. On a site server, a person who signs in by email and PIN acts on their site role for every site function: operating the plant (device commands and acknowledgements), site administration (site users, API keys, configuration), and site engineering. A principal with an org role uses that role instead, as described below.

A site server with local email + PIN login carries its own site-local user roster, managed on the site server itself via /api/site/users — by a site user whose site role carries admin authority, fully offline, or by an organisation owner or admin signed in with their organisation account. Each site user holds a site role, stamped into locally issued tokens (site_role); the roster shows Owner, Admin, Member, Site admin, Engineer, Operator, Viewer and Restricted. Owner, Admin and Site admin carry site administration (site users, API keys, configuration); a Site admin grants no role above its own and cannot create API keys. On a site that accepts plant commands, Owner, Admin and Member may operate the plant, and so, under the default setting, may Site admin, Engineer and Operator. Viewer never does, and Restricted sees no site data at all. Plant reconfiguration is covered under Who may operate a site.

On a site server a principal’s effective role is its org role if it has one, falling back to its site role; a site role grants nothing on the cloud — it authorises the site-local surface only. Site-PIN login itself is covered in Authentication.

Who may operate a site

Note

Inside a tenant, membership is the gate for operating: any member may issue plant commands on the sites they can reach, and plant reconfiguration is held narrower (below). Each site also declares whether it accepts Consystence commands at all. Only a site where Consystence is declared the operator surface (native) accepts them; a site declared display-only, a site declared as operated from another SCADA and a site that has declared no operator surface refuse every plant write. Commands from the hosted service also need the site’s remote operation enabled. During the beta, production control stays with the site’s existing control system.

• The tenant boundary holds. A member of organisation A cannot drive organisation B’s sites.
• Plant reconfiguration — registering a controller, activating data points or rebinding pipeline tags — redefines what the plant is rather than operating it as configured, so it is held narrower than membership: to a tenant owner or admin, or, on a site server, a user signed in by site PIN whose site role is owner, admin, site admin or engineer. People make these changes on the engineering pages; the matching API endpoints require owner or admin, and other members keep read access to data points. The assistant is never offered these actions. Consystence does not load code into a site’s plant controllers: the site’s engineers do that under the site’s own change control.
• API keys stay within this. A key is read-only unless it is an operator key, which acts for one named member on one native site and can issue commands and acknowledge alarms there; see Tenant API keys.

Access also determines which AI tools a member may invoke. AI in Consystence is advisory: it reads tags and controller configuration, explains what it finds and recommends. The same role/access vocabulary gates that tool surface.

AI is advisory-only

AI reads, explains and recommends; it never commands equipment. No role or access grant turns the AI into a control authority. Hard interlocks live in IO modules and safety relays, independent of any software role. See the platform overview for the advisory boundary.

Platform administrators

A platform administrator is a member of Consystence operations staff who can enter a tenant for support, diagnostics and onboarding.

Two clarifications matter:

• A platform administrator is not an organisation owner. It is an operational capability outside the per-tenant role model, not a higher tenant role.
• A platform administrator is not an organisation’s licence-assignment authority. Licences are signed by the account control plane and assigned by the organisation’s owner or admin. Consystence operations staff can also grant entitlements and licence pools through the account control plane’s support path. See Licensing.

Roles, tiers and licences are distinct

Do not conflate the membership role with the organisation’s commercial entitlement:

• A membership role governs who may administer the tenant.
• An organisation tier (Free sandbox, Integrator or Enterprise; see plans) and SKU pools of install capacity (SiteServer / Edge / Agent) govern what the organisation is licensed for.

Crucially, licence grace or expiry degrades behaviour but never gates operator control writes — a lapsed licence does not strip a member’s ability to operate the plant. The two systems are independent; see Licensing for the entitlement model.

Tenant isolation (resource-to-org authorisation)

The role model assumes a caller acts on their own tenant’s resources. That binding is made explicit and enforced separately: before touching a tenant-scoped resource, a request derives the resource’s owning organisation from the resource identifier (a site code maps to an org), then validates that organisation against the caller’s membership (by oid). A member of organisation A reaching organisation B’s resources is denied; platform administrators are the exception described under Platform administrators. It is defence-in-depth on top of the membership and access checks described above, not a replacement for them.

Auditing of authority changes

Access changes are recorded in the operational journal, the permanent record that also holds device commands and alarm acknowledgements. Recorded changes include:

• approving, rejecting and revoking members;
• role changes;
• creating and revoking API keys;
• changes to site users.

A blocked attempt to remove an organisation’s last owner or admin is recorded with its refusal. Each record names the person or system that acted, taken from the authenticated identity, never supplied by the request. The hosted service and each site server keep separate journals: a change made on a site server is recorded in that server’s own journal.

Related

• Authentication — how membership is resolved from each credential type
• Organisations & sites — the tenant and site model roles apply within
• Licensing — tiers and SKU pools, distinct from roles
• API reference — administrative endpoints, including tenant API-key management