Roles & Permissions

Access Management

Users and Roles are managed together in Settings → Access Management. This page has five tabs — Users, API Users, Roles, Entities, and Report — with count badges showing the number of items in each.

• Users — Manage user accounts (create, edit, delete, activate/deactivate)
• API Users — Manage API service accounts and keys (see API Keys)
• Roles — Create roles and assign permissions
• Entities — Assign approvers to entities that require approval workflows
• Report — Read-only cross-cutting permissions overview (see Permissions Report)

Users tab:

Manage user accounts. Each user has an email (login name), display name, password, and role memberships.

The email address is the unique identifier for each user account. It serves as the login name and must be unique across the system — the database enforces this constraint. If you try to create a user with an email that already exists, you will get an error.

The Users tab shows all accounts with their display name, email, active/inactive status, and assigned roles. Each user card has edit, delete, and resend welcome email buttons.

Creating a user:

1. Click New user
2. Fill in the required fields:
   • Email — The unique login name (must be a valid email format, must be unique — duplicates are rejected)
   • Display Name — Shown in the app (settings menu, toolbar)
   • Password — Enter manually or click Generate to create a strong 16-character random password with the show/hide toggle to verify
3. Optional settings:
   • Must change password — Forces the user to set a new password at next login (default: on for new users)
   • Send welcome email — Sends a branded welcome email with login credentials, role overview, and sign-in link (default: on for new users)
   • Active — Toggle to enable/disable the account (with green/red status badge)
4. Select one or more roles from the checkbox list to control permissions
5. Click Create user

Welcome email:

When the "Send welcome email" checkbox is enabled, a branded HTML email is sent to the new user after creation. The email includes:

• A welcome message with Primentra branding
• When "Must change password" is enabled: a secure one-click sign-in link (valid 72 hours, one-time use) — no plain-text password is included
• When "Must change password" is not enabled: login credentials (email and password) plus a sign-in button
• An overview of assigned role memberships
• A sign-in button or link directing to your Primentra instance

You can also resend the welcome email to existing users by clicking the mail icon on any user card. Resent emails do not include the password (since it is not stored in plain text).

Email sending is non-blocking — if SMTP is not configured or the email fails to send, the user creation still succeeds. A toast notification shows whether the email was sent successfully.

Editing a user:

Click the edit icon on any user card. You can change all fields. Leave the password field empty to keep the current password. Changes to role memberships take effect immediately after saving.

Deleting a user:

Click the delete icon and confirm in the dialog. Deletion is permanent and cascades:

• Role memberships are removed
• User favorites are removed
• User settings are removed
• Audit log entries created by the user are preserved (the UserId remains as a numeric reference for traceability)

Account lockout:

When a user enters the wrong password 5 times consecutively, their account is automatically set to Inactive. The failed attempt counter is visible to administrators. To unlock:

1. Open the locked user's edit form
2. Check the Active toggle
3. Save — the failed attempt counter resets automatically on the next successful login

Audit trail:

All authentication events are logged in the audit log with entity name Authentication and model System (these are reserved names that cannot conflict with your own entities):

Each entry includes the user's email and IP address (when available). Security events (login, user management) show event details — email, IP address, and display name — instead of a field-changes table. View these entries in Settings → Logs → Audit Log by filtering on entity "Authentication".

Roles & Permissions

Permissions in Primentra are always granted through roles — there are no per-user permissions. This design keeps access control transparent: to understand what a user can do, check their role memberships.

Roles collect users with shared access levels. Permissions control what each role can see and edit. Roles are managed from the Roles tab in Settings → Access Management.

Create a role:

1. Go to Settings → Access Management → Roles tab
2. Click New role
3. Enter: Name, Description, and Member email addresses
4. Click Save

CRUD permissions (model and entity scope): At model and entity level, permissions are granular with four independent operations plus a Moderator flag:

• C (Create) — Add new rows, import data, paste rows
• R (Read) — View data in the grid and export
• U (Update) — Edit existing cell values, bulk edit, fill handle
• D (Delete) — Remove rows, purge entity data
• Mod (Moderator) — Automatically grants full CRUD + access to entity/model configuration

Rules:

• Enabling Create, Update, or Delete automatically enables Read
• Enabling Moderator automatically enables all four CRUD operations
• Multiple roles: the most permissive combination wins (OR-union). Example: Role A grants Read, Role B grants Create+Read+Update — the user gets CRU

Moderator forces all attributes to Write: When an entity (or model) has Moderator enabled — either directly or inherited — all attributes are automatically forced to Write ↑. The attribute dropdowns become disabled and cannot be narrowed down. This prevents the confusing situation where an admin accidentally restricts a field while the entity already has full Moderator access.

When you save permissions, any leftover attribute overrides under a Moderator entity are automatically cleaned up. If you later remove the Moderator flag, attribute dropdowns become interactive again and you can set individual Read/Write levels.

Permission levels (attribute scope):

• None — No access
• Read — View field only
• Write — Edit field

Attribute-level permissions control individual field visibility and editability. They use simple Read/Write levels, not CRUD toggles.

Permission scopes (from broad to specific):

• Model — Sets CRUD defaults for all entities in the model
• Entity — Overrides the model default for one specific entity
• Attribute — Overrides entity/model for a single field (Read or Write only)

Permissions inherit downward: an attribute inherits from its entity, which inherits from its model. A direct permission always overrides an inherited one (shown with ↑). Use the × button to clear an override and revert to inherited.

Multi-role conflict resolution: When a user belongs to multiple roles, the most permissive combination wins (OR-union). For example, if Role A grants Read on an entity and Role B grants Write, the user gets Write. This applies at every scope level — model, entity, and attribute.

Server-side enforcement: All CRUD permissions are enforced server-side. Even if a user bypasses the UI, the API will reject unauthorized operations with HTTP 403.

Edit permissions:

1. Click Edit permissions on a role
2. Expand models to see entities and attributes
3. Toggle C/R/U/D buttons for model and entity scope, or use Mod for full access
4. For attributes, select Read or Write from the dropdown
5. Click Save permissions to apply changes

Audit logging of permission changes:

Every permission change is automatically recorded in the audit log with Action = permission_change. Each individual permission change is a separate audit entry — saving a role's permissions in one click may produce many entries, one per changed permission. This gives maximum granularity for compliance auditing.

Each entry's Details field is a JSON object capturing exactly what changed:

{
  "scope": "entity",
  "modelId": 3,
  "modelName": "Customer",
  "entityId": 12,
  "entityName": "Branch",
  "roleId": 2,
  "roleName": "DataSteward",
  "changes": {
    "canRead": { "from": false, "to": true },
    "canUpdate": { "from": true, "to": false }
  }
}

For attribute scope, the changes object contains level (from/to) instead of CRUD flags:

{
  "scope": "attribute",
  "modelId": 3,
  "modelName": "Customer",
  "entityId": 12,
  "entityName": "Branch",
  "attributeId": 47,
  "attributeName": "PostalCode",
  "roleId": 2,
  "roleName": "DataSteward",
  "changes": {
    "level": { "from": "none", "to": "read" }
  }
}

The permission update and audit log insert always succeed or fail together — no partial writes.

Use cases — common permission setups:

1. Read-only viewers Give a team view-only access to a model so they can see data but not change anything.

┌───────────────────────────────────────┐
│  Role: "Finance Viewers"           │
├───────────────────────────────────────┤
│  MODEL: Financial Data  →  [R]     │
│  ├─ Cost Centers        →  R ↑     │
│  │  ├─ Code            →  Read ↑  │
│  │  ├─ Name            →  Read ↑  │
│  │  └─ Budget          →  Read ↑  │
│  └─ Accounts          →  R ↑     │
│     ├─ Account Nr      →  Read ↑  │
│     └─ Description     →  Read ↑  │
└───────────────────────────────────────┘

Set Read (R) at the model level. All entities and attributes inherit Read automatically. Users can view and export data, but every edit button and import action is hidden.

2. Full editors with one sensitive field locked The team can edit everything, except one confidential field that stays read-only.

┌───────────────────────────────────────┐
│  Role: "HR Editors"                 │
├───────────────────────────────────────┤
│  MODEL: HR Data  →  [CRUD]          │
│  ├─ Employees       →  CRUD ↑       │
│  │  ├─ Code          →  Write ↑    │
│  │  ├─ Name          →  Write ↑    │
│  │  ├─ Department    →  Write ↑    │
│  │  └─ Salary     ⚠️  →  Read       │
│  └─ Departments     →  CRUD ↑       │
│     └─ (all fields)  →  Write ↑    │
└───────────────────────────────────────┘

Set CRUD at the model level for full access. Then override the Salary attribute to Read. The field shows in the grid with a lock icon — visible but not editable. All other fields inherit Write from the entity.

3. Data steward with Moderator Grant a team lead full access including configuration rights. All attributes are forced to Write — no individual overrides possible.

┌──────────────────────────────────────────┐
│  Role: "Product Data Stewards"              │
├──────────────────────────────────────────┤
│  MODEL: Product Catalog  →  [Mod]           │
│  ├─ Products            →  Moderator ↑     │
│  │  ├─ Code     🔒      →  Write ↑  (locked) │
│  │  ├─ Name     🔒      →  Write ↑  (locked) │
│  │  ├─ Category 🔒      →  Write ↑  (locked) │
│  │  └─ Price    🔒      →  Write ↑  (locked) │
│  └─ Categories          →  Moderator ↑     │
│     └─ (all fields) 🔒  →  Write ↑  (locked) │
└──────────────────────────────────────────┘

Set Moderator at the model level. Every entity inherits Moderator, and every attribute is forced to Write ↑ with disabled dropdowns. The lock icon means the dropdown is not interactive — Moderator overrides everything. If you later remove Moderator, the dropdowns unlock and you can set individual levels again.

4. Partial editing — read model, write one entity Most entities are view-only, but one entity is editable for data entry.

┌───────────────────────────────────────┐
│  Role: "Region Managers"            │
├───────────────────────────────────────┤
│  MODEL: Geography  →  [R]           │
│  ├─ Countries       →  R ↑  (view)  │
│  ├─ Provinces       →  R ↑  (view)  │
│  └─ Regions      ⭐  →  [CRU]       │
│     ├─ Code          →  Write ↑    │
│     ├─ Name          →  Write ↑    │
│     └─ Province      →  Write ↑    │
└───────────────────────────────────────┘

Set Read (R) at the model level. Then override the Regions entity with Create, Read, and Update (CRU) — no Delete. The team can view all geography data, but only add and edit records in Regions. Countries and Provinces stay read-only.

5. Multiple roles — most permissive wins A user belongs to two roles with different access levels. The system takes the most permissive combination.

┌───────────────────────────────────────────┐
│  User: jan@company.com                       │
├───────────────────────────────────────────┤
│  Role A: "Viewers"                            │
│  └─ Products entity  →  [R]                  │
│                                               │
│  Role B: "Product Editors"                    │
│  └─ Products entity  →  [CRU]                │
│                                               │
│  ───────────────────────────────────────── │
│  Result: Jan gets [CRU] on Products           │
│  (OR-union: R + CRU = CRU)                    │
└───────────────────────────────────────────┘

Jan belongs to "Viewers" (Read only) and "Product Editors" (Create, Read, Update). The system combines both roles using an OR-union and grants the most permissive result: CRU. This works at every level — model, entity, and attribute. You never have to worry about one role blocking another.

CRUD Combination Reference

Auto-grant rules:

• Enabling C (Create), U (Update), or D (Delete) automatically enables R (Read) — you cannot write without seeing
• Enabling Mod (Moderator) automatically enables all four: C, R, U, D
• Disabling R (Read) automatically disables C, U, and D — removing view access removes all write access
• Each permission is independent otherwise — D does not require U, and C does not require U

All effective combinations:

Attribute-level permissions:

Attributes use simpler Read/Write levels that work together with the entity-level CRUD:

The entity-level permission determines which operations are available. The attribute-level permission determines which fields are editable during those operations. Both must allow it for the user to edit a specific field.

Examples:

• Entity = CRU, Attribute "Salary" = Read → User can create and edit rows, but the Salary field is always locked (visible but not editable)
• Entity = R, Attribute "Name" = Write → User can only view — the Write attribute permission has no effect because the entity does not allow editing
• Entity = CRUD, Attribute "Code" = Write → User has full access to the Code field (create, edit, delete rows, field is editable)
• Entity = RD, Attribute "Name" = Write → User can view and delete rows, but cannot edit the Name field (entity has no Update permission)

Domain fields (dropdown attributes)

When an attribute is of type Domain — it shows a dropdown of values from another entity — the same attribute-level permission rules apply:

Does the user need rights on the referenced entity? No. Domain dropdown options are always loaded from the referenced entity regardless of whether the user has direct access to that entity. Permissions on a referenced entity control whether the user can open and browse that entity directly — they do not affect its use as a domain value in other entities.

Example: A user has Read on entity Branch and Write on the attribute Area (a domain field pointing to the Area entity). The user has no rights on Area itself.

• ✅ The Area dropdown appears on Branch records — user can change the area.
• ✅ All available areas are listed in the dropdown.
• ❌ The Area entity does not appear in the sidebar — user cannot browse Area records directly.

Preview As

Preview As lets administrators view the application through another user's or role's effective permissions — without logging out or opening a second browser window.

This is useful for verifying that permissions are configured correctly before handing an account over to a user.

How to use it:

1. Open Settings → Preview as...
2. Pick a tab: As User (preview as a specific user) or As Role (preview as any member of a role)
3. Search and select the user or role
4. Click Start Preview

A blue banner appears at the top of the screen:

What changes during preview:

• The sidebar shows only the entities accessible to the selected user/role
• The dashboard reflects their KPI counts and recent activity
• All write operations are disabled — the DataGrid is read-only
• The notification bell and admin-only widgets are hidden if the preview identity is not an administrator

What stays the same:

• You remain logged in as yourself — your session is not affected
• The Settings menu (gear icon) stays fully active for you. Administration, Migration Wizards, and all admin tools remain accessible. The preview only affects what the data sidebar and DataGrid show — not your own admin controls
• No data can be modified during preview

Ending preview:

Click Exit Preview in the blue banner, or simply refresh the page. The preview state is never saved to the database or local storage.