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, the sole authority for every site function on that server — 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, including other owners. The irreducible root of the organisation.
admin	Full — manage members, domains, licences and sites	Manages members, but cannot demote or revoke an owner.
member	None	None. (Control access is a separate dimension — see the interim posture below.)

The subset that confers tenant-administration authority is AdminAuthority = {owner, admin}. Administrative surfaces (managing the tenant’s members, sites, edges, credentials and configuration) are gated on this subset; a member is denied. Roles are compared case-insensitively.

Note

A membership role is not read from a bearer token. For cloud sessions it is resolved server-side from the membership grain, 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 must always retain at least one owner (never exactly one — a single-owner org would brick its own administration the moment that owner is lost). Multiple owners are permitted and expected.
• An admin cannot demote or revoke an owner. Only an owner manages owners. This closes the co-administrator coup: with two or more admin-authority members, an admin must not be able to strip another (including the founder). For a partner organisation that has granted an integrator admin access, the partner’s ownership remains unstrippable by that integrator.

Target model — enforcement forthcoming

These owner-protection invariants are ratified, with enforcement forthcoming. The guard shipped today is last-admin protection — an org must retain at least one owner-or-admin. Treat owner protection as the target model until it lands.

Last-admin and owner protection

The platform refuses changes that would leave an organisation unadministerable. The shipped guard prevents removing the last admin-authority member; the owner-protection invariant (at least one owner; admins cannot touch owners) will extend it when it ships. A blocked “remove the last admin” attempt is rejected (HTTP 409); it is a security-relevant event, and durable audit of blocked attempts is forthcoming (see Auditing).

Caution

Owner-protection introduces a recovery edge case: a locked-out sole owner cannot be recovered through normal organisation administration. Recovery is by a platform-administrator ownership transfer or re-seed, triggered by a manual support request and recorded — once the durable audit ledger lands — as a cross-tenant authority change. 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 the interim posture below, not by groups.

Site roles on a site server

Site roles are a separate authorisation plane from org membership, and on a site server they are the sole authority for every site function: operating the plant (device commands and acknowledgements), site administration (site users, API keys, configuration), and site engineering and deploy. Org membership roles, conversely, govern only tenant management and membership.

A site server with local email + PIN login carries its own site-local user roster, managed via /api/site/users — by an org admin from the cloud, or on the site server itself by a site user whose site role carries admin authority, fully offline. Each site user holds a site role, stamped into locally issued tokens (site_role); the UI displays the roster as Owner / Admin / Engineer / Operator / Viewer. A site role of admin or owner carries full site-administration authority (site users, API keys, configuration); the plant-reconfiguration actions described in the interim posture below are held narrower still, at admin alone.

On the Site binary 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.

Interim posture: full control for members

Interim behaviour, not a steady state

Until the access-group model lands, any authenticated member of a tenant has full control over the sites they can reach within that tenant. The gate is tenant membership, not per-capability access.

This interim is deliberate and recorded with an explicit closure condition:

• The widening is intra-tenant only. The tenant boundary is still enforced cross-tenant — a member of organisation A cannot drive organisation B’s sites. The widening affects only what a member can do inside their own tenant.
• A narrow set of plant-reconfiguration actions (activating data points, rebinding pipeline tags, registering a controller, deploying controller code) is held at admin only on the assistant’s tool surface and the deploy-confirmation gate — there, both member and owner are denied, pending the access-group model — because these redefine what the plant is rather than operate it as configured. The dividing line is operate-as-configured (allowed for members) versus change-the-configuration (held at admin). On a site server, a site-PIN principal whose site role is admin satisfies the same gate. The equivalent administrative API endpoints sit at admin authority (owner or admin), and routine data-point management on the API is available to any tenant member.
• Closure condition: the per-capability access model replaces “full access for members” with granular, audited access. This must close before the first live-controllable, multi-member customer site exists.

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

AI is advisory-only

AI configures, queries, classifies and explains; 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 Consystence operations staff — a verified @consystence.com identity (or an explicit seed list). It is a bypass used for support, diagnostics and onboarding: a platform administrator can enter any tenant. Cross-tenant actions are logged (each captured as the platform-administrator acting into the target organisation), and durable audit of them is forthcoming. The bypass is also not universal: the tenant-scoped admin endpoints (/api/admin/orgs/{slug}/*) deliberately have no platform-admin override — platform staff must themselves be an org-admin member of the target org to use them.

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 the licence authority. Licensing (organisation tier and per-seat pools) is issued by the account control plane and mediated by the cell; the platform-admin bypass does not grant or alter licences. 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 (Basic, or a paid tier from the Integrator or Enterprise family) and per-seat licence pools (SiteServer / Edge / Agent) govern what the organisation has paid 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; a platform administrator bypasses (logged; durable audit is forthcoming). It is defence-in-depth on top of the membership and access checks described above, not a replacement for them.

Auditing of authority changes

Forthcoming

The durable authority-audit ledger is not yet built. Today, membership approvals, rejections, revocations and role changes emit operational log lines (actor principal-derived); durable, queryable authority audit is forthcoming. The durable audit trail that does exist in the current build covers device command execution.

When the ledger lands, exercises of admin authority will be durably audited — appended to an immutable, queryable, per-organisation sink (not a transient log line). Audited events will include:

• granting or removing {owner, admin} (crossing the admin-authority line);
• access grants (when the access model lands — granting access is itself an authority action);
• every blocked last-admin or owner-protection attempt;
• cross-tenant authority changes such as a platform-administrator ownership transfer.

The actor on every record is principal-derived (never client-supplied). Lower-churn changes — ordinary role changes among non-admin members, logins and views — remain operational log lines rather than durable records.

Related

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