Permissions and scoping
This page is the look-up reference for Erde authorization: the global-role-by-action matrix, the rules for Project-scoped versus Site-scoped data, and how locking an aggregate affects writes. For the model behind these tables, see Users, roles, and permissions.
Authorization combines two independent layers. A global role on the user account gates whole API endpoints; a per-Site or per-Project membership role gates reads and writes on individual records. Both must pass.
Global roles
Every account holds exactly one global role, required at creation. The wire and storage value is the code; the interface shows the label.
| Role code | Label |
|---|---|
Admin | Administrator |
DataManager | Data Manager |
Manager | Manager |
Staff | Staff |
All four roles are internal users — they belong to the RequireInternalUser policy set.
Administrator and Data Manager carry a global-admin bypass: they can view, add, edit, and manage every Site and Project without a membership row. Deleting a Site or Project aggregate is reserved for Administrator alone.
Endpoint policies
Whole API endpoints are gated by one of four named policies, each mapped to a fixed set of global roles.
| Policy | Roles allowed | Gates |
|---|---|---|
RequireAdmin | Administrator | System settings, client configuration, admin dashboard, system audit log, demo-data seeding |
CanManageUsers | Administrator | Creating accounts, assigning global roles, locking, deleting, resetting passwords |
RequireDataSteward | Administrator, Data Manager | Reference data, Data Management Plans (DMPs) |
RequireInternalUser | Administrator, Data Manager, Manager, Staff | Reading business and vendor data (laboratories, organizations) |
CanManageUsers resolves to the same role set as RequireAdmin today, but stays a distinct policy because it expresses a different concern — user administration — and may diverge later.
Write access to system catalog entities (Equipment, Contact, Organization, Laboratory) is not one of the four named policies. It is granted to Administrator, Data Manager, and Manager through a server-side guard, which is what backs the Manager column on the "Write system catalog entities" row of the permissions matrix.
Permissions matrix
Actions are rows; global roles are columns. Yes means the global role grants the action on its own. Scoped means the action additionally requires the matching per-Site or per-Project membership role (see Scope rules). — means not granted.
| Action | Admin | Data Manager | Manager | Staff |
|---|---|---|---|---|
| System settings, admin dashboard, audit log, demo seed | Yes | — | — | — |
| Create accounts, assign roles, reset passwords | Yes | — | — | — |
| Manage reference data, screening programs, DMPs | Yes | Yes | — | — |
| Read business and vendor data (labs, organizations) | Yes | Yes | Yes | Yes |
| Write system catalog entities (Equipment, Contact, Organization, Laboratory) | Yes | Yes | Yes | — |
| Create a Site or Project aggregate | Yes | Yes | — | — |
| Delete a Site or Project aggregate | Yes | — | — | — |
| Toggle a Site or Project lock | Yes | Yes | — | — |
| Manage Project–Site links and Programs | Yes | Yes | — | — |
| Validate project data | Yes | Yes | — | — |
| View site infrastructure data | Yes | Yes | Scoped | Scoped |
| Add site infrastructure data | Yes | Yes | Scoped | Scoped |
| Edit site infrastructure data | Yes | Yes | Scoped | Scoped |
| Manage a site's membership | Yes | Yes | Scoped | Scoped |
| View project data | Yes | Yes | Scoped | Scoped |
| Add project data | Yes | Yes | Scoped | Scoped |
| Edit project data | Yes | Yes | Scoped | Scoped |
| Manage a project's membership | Yes | Yes | Scoped | Scoped |
Validating project data requires both data-steward access — the RequireDataSteward role set (Administrator or Data Manager) — and Editor-or-higher membership on the project; a global-admin bypass (held by both Administrator and Data Manager) covers the membership half. Manager and Staff have no global-admin bypass — every scoped action they take comes entirely from a membership row.
Scope rules
Domain records belong to a Site or a Project. Membership grants a tiered role on that scope; each tier includes everything the lower tiers can do.
| Scope | Covers | View | Add | Edit | Manage membership |
|---|---|---|---|---|---|
| Site | Site infrastructure: Locations, Wells, Boreholes, Test Pits, Sediment Cores, plus field-monitoring data: Water Levels, Well Purges, Field Parameters, logger streams | Viewer | Contributor | Editor | Site Manager |
| Project | Project data: Samples, Lab Analyses, Lab Reports | Viewer | Contributor | Editor | Project Manager |
The two scopes are intentionally asymmetric, because field data must reference the Site it was collected at:
| Holding this role | Grants on its own scope | Grants on the other scope |
|---|---|---|
| A Site role | View and modify Site infrastructure | No access to project data at the Site |
| A Project role | View and modify project data | View-only on infrastructure of any linked Site |
| A Project Contributor or higher | View and modify project data | View and add infrastructure at any linked Site |
A Project Contributor can therefore add a needed Location at a linked Site without holding a separate Site Editor role; Viewer project roles do not gain this. Access reached through a Project never works in reverse — a Site role does not grant access to any Project.
Locking effects
Every Site and Project aggregate carries an IsLocked flag (default off). Locking freezes all writes to that aggregate and every record scoped to it; reads are unaffected. Locked records still appear and export normally.
| Aspect | Behavior when locked |
|---|---|
| Reads | Unaffected — records remain visible and exportable |
| Create, edit, or delete scoped records | Blocked; the API returns 409 Conflict |
| Who may toggle the lock | Administrator or Data Manager only |
| How the flag is set | Only through dedicated Lock and Unlock actions, never a normal save |
The enforcement runs at the database boundary, so any write that touches a record under a locked Site or Project is rejected before it reaches the database — regardless of which screen or import path attempted it. The IsLocked flag is deliberately absent from the Save forms; it changes only through the Lock and Unlock actions. Lock state is independent of permission: a user who may otherwise edit a record still cannot write to it while its Site or Project is locked.
Locking a Site or Project blocks all edits, additions, and deletions to its data until an Administrator or Data Manager unlocks it. Manager-tier roles can edit data but cannot freeze it.
Related
- Users, roles, and permissions — the two-layer model behind these tables
- Manage users and roles — create accounts and assign global roles
- Aggregates, locking, and auditing — how scoped writes are governed
- Glossary