Users, roles, and permissions
Erde controls who can see and change data through two independent layers: a global role on each user account that gates system-wide features, and scoped membership roles that grant access to a specific Site or Project. A user's effective rights are the combination of both. This page explains the model; the permissions matrix and the add-a-user task live in Administration.
Two layers of access
Authorization in Erde answers two separate questions, and both must pass:
- What can this account do system-wide? Decided by the account's global role — applied to whole API endpoints (for example, who may open system settings or create user accounts).
- What can this account do to this Site or this Project? Decided by per-Site and per-Project membership roles — checked inside the service for the specific record being read or changed.
Holding a global role does not, by itself, grant access to an individual Site's or Project's data — that comes from membership. The one exception is the two top global roles, which bypass scoped checks (covered below).
Figure: a user's effective permissions combine a global role with per-Site and per-Project membership.
Global roles
Every account holds exactly one global role. The role is required at creation and can be changed later — there is no role-less account. A role's wire and storage value is its code; the label shown in the interface is in the second column.
| Role code | Label |
|---|---|
Admin | Administrator |
DataManager | Data Manager |
Manager | Manager |
Staff | Staff |
Each account holds exactly one role; an endpoint policy admits the account when its role is one of the policy's allowed roles.
Endpoint policies
Whole API endpoints are gated by one of four named policies. Each policy maps to a fixed set of global roles. Every endpoint requires an authenticated user by default, so anonymous access is the exception, not the rule.
| Policy | Roles allowed | Gates |
|---|---|---|
RequireAdmin | Administrator | System settings, client configuration, admin dashboard, system audit log, demo-data seeding |
RequireDataSteward | Administrator, Data Manager | Reference data, regulatory and screening programs, Data Management Plans |
CanManageUsers | Administrator | Creating accounts, assigning global roles, locking, deleting, resetting passwords |
RequireInternalUser | Administrator, Data Manager, Manager, Staff | Reading business and vendor data (labs, organizations) |
CanManageUsers resolves to the same role set as RequireAdmin today, but it stays a distinct policy because it expresses a different concern — user administration — and may change independently later.
A Data Steward is any user the RequireDataSteward policy admits — an Administrator or a Data Manager. The role gives day-to-day authority over shared reference data without full system administration. See the glossary.
Scoped data access
Domain records belong to a Site or a Project, and access to them is granted by membership rather than by a global role. Each membership row carries a tiered scoped role; higher tiers include everything the lower tiers can do.
| Tier | Site role | Project role | Grants on that scope |
|---|---|---|---|
| 1 | Viewer | Viewer | View data |
| 2 | Contributor | Contributor | Add data |
| 3 | Editor | Editor | Edit data |
| 4 | Site Manager | Project Manager | Manage membership |
Site scope covers a Site's physical infrastructure — its Locations, Wells, Boreholes, and related field artifacts. Project scope covers project data — Samples, Lab Analyses, and Lab Reports.
How the two scopes interact
The two scopes are intentionally asymmetric, because field data must reference the Site it was collected at:
- A Site role grants view and modify rights on that Site's infrastructure, but no access to project data at the Site.
- A Project role grants view and modify rights on that Project's data, and view-only access to the infrastructure of any Site the Project is linked to — needed for sample context.
- A Project Contributor or higher additionally gains the right to add (but not edit or manage) infrastructure at a linked Site. This lets a project contributor add a needed Location without holding a separate Site role. Viewer project roles do not.
The two top global roles bypass scope
Administrator and Data Manager carry a global-admin bypass: they can view, add, edit, and manage every Site and Project without an explicit membership row. Manager and Staff have no bypass — their Site and Project access comes entirely from membership. Deletion of a Site or Project aggregate is reserved for Administrator alone.
How it fits together
| Aspect | Global role | Scoped membership |
|---|---|---|
| Where it lives | The user account | A Site or Project membership row |
| What it gates | Whole API endpoints (policies) | Reads and writes on one Site or Project |
| Granularity | System-wide | Per Site, per Project |
| Tiers | 4 roles | Viewer → Contributor → Editor → Site/Project Manager |
| Bypass | Administrator and Data Manager bypass scoped checks | — |
Scoped records expose their owning Site or Project through marker interfaces (ISiteScoped and IProjectScoped). Those markers drive locking and auditing, not authorization — the access checks themselves run in the service layer against the record's Site and Project identifiers.
Related
- Permissions and scoping — the full role-by-action matrix
- Manage users and roles — create accounts and assign roles
- Sites and projects — the two organizing scopes
- Aggregates, locking, and auditing — how scoped writes are governed