Authorization

Authorization defines what users can and cannot do after authentication. Aptli combines two independent layers: permissive admin rights (what you can do) and restrictive role restrictions (what you cannot see). Together they give administrators fine-grained control over both capabilities and data visibility.

Authorization Model Overview

Aptli's full security model has three layers:

1. Authentication — Who you are (covered in the Authentication section)
2. Admin Rights — What you CAN modify (permissive grants)
3. Role Restrictions — What you CANNOT see (restrictive filters)

All restrictions are enforced on the server — unauthorized data is never sent to your browser, regardless of what you try through the UI, API, or exports.

This model provides tremendous flexibility while maintaining security.

Admin Rights (Permissive)

Admin rights grant permission to modify information or alter status. Without these rights, users can only view data and edit their own profile.

Admin rights are an à-la-carte, per-user array (user.admin). Each entry is a single right name; there is no grouping into bundles. Rights are granted directly on the user, never inherited from a role.

Common Admin Rights:

• usersUpdate - Edit other users' profiles (name, title, division - NOT email/password)
• usersLogout - Force logout or hard lock users
• usersDelete - Delete user accounts
• usersCreate - Create new users or undelete accounts
• featureCreate, featureUpdate, featureDelete - Modify map features (points, lines, polygons)
• allowCommits - Commit map versions live (otherwise Submit is a request for admin review)
• jobsCreate, jobsUpdate, jobsDelete - Manage jobs (planned units of work)
• workOrdersCreate, workOrdersUpdate, workOrdersDelete - Manage work orders
• reportsCreate, reportsUpdate, reportsDelete - Submit and manage work reports
• validationsCreate, validationsUpdate, validationsDelete - QA sign-off on reports
• activitiesCreate, activitiesUpdate, activitiesDelete - Maintain the activity (work-type) catalogue
• projectsCreate, projectsUpdate, projectsDelete - Manage projects
• transactionsCreate - Create inventory transactions (the ledger is insert-only — there is no update or delete right)
• canFacilitatePickups - Dispense materials to a person via a QR pickup on their behalf
• canTransferStock - Move stock between sites (sites are transfers, people are pickups)

Filing a help request needs no right — any authenticated user can raise one. Whether the AI assistant is available is a deployment-wide setting, not a per-user right.

Super Rights (Supercede All Others):

• appSettingSchemasModify - Modify application-level settings (domains, timeouts, security)
• adminRightsModify - Grant admin rights to other users
• viewDeleted - See deleted records (nearly universal, partially overridden by role restrictions)

Checking User's Admin Rights:

1. Navigate to Admin → Users
2. Open user profile
3. "Admin Rights" section lists all granted permissions

Role Restrictions (Restrictive)

Roles are collections of restrictions that prevent viewing and altering records with certain characteristics. A role holds only a name and a list of restrictions — nothing else. Roles do not carry members, an owner, or admin rights. Membership lives on the user: each user has a roles list, and every restriction from those roles is applied to that user.

To assign a role, add it to the user from their profile (or set it as a default role for new users). To list a role's members, search users whose roles include it.

Role Components:

• Name - A human-readable label
• Role Restrictions - Field-level filters hiding specific data

Roles scope visibility and restrictions only. They never grant the ability to do anything — that is what admin rights are for.

Role Restriction Structure

Each restriction defines:

• Model (target_model) - Which data type (user, feature, role, etc.)
• Field - Which property to filter on (owner, status, category, custom fields)
• Comparison - How to match. One of: eq, ne, gt, gte, lt, lte, in, nin
• Filter Value - What value to match against (a single value, or an array for in/nin)
• Permissions - An array of the operations that are denied when a record matches. Each entry is one of read, edit, create, delete. Listing an operation here blocks it; leaving it out allows it.

The roles administration UI presents these as model / action / path columns.

Example Use Case: Contractor Separation

Scenario: Prevent Contractor A from seeing Contractor B's work

Setup:

1. Create role: "Contractor A"
2. Add role restriction:
   • Model: feature
   • Field: owner
   • Comparison: eq
   • Filter Value: Contractor B
   • Permissions (denied): read, edit, create, delete (all four blocked)
3. Add the "Contractor A" role to Contractor A's users (from each user's profile)

Result:

• Contractor A members cannot see any features where owner = "Contractor B"
• Not just hidden in UI - API returns data as if records don't exist
• Cannot accidentally see via screenshot, API call, or export
• Fully server-side enforced

Additional Use Cases

By Work Stage: Prevent field workers from seeing QC validation reports:

Role: "Field Workers"
Restriction:
  Model: validation
  Field: status
  Comparison: ne
  Filter Value: "" (any value)
  Permissions (denied): read

Field workers cannot see validations at all.

By Asset Type: Separate infrastructure teams (poles/ducts vs. active equipment):

Role: "Civil Team"
Restriction:
  Model: feature
  Field: category
  Comparison: eq
  Filter Value: "Active Equipment"
  Permissions (denied): read, edit, create, delete

Civil team cannot see or modify active equipment features.

By Physical/Logical: Separate office data access (capacity relationships vs. office locations):

Role: "Capacity Analysts"
Restriction:
  Model: feature
  Field: layer
  Comparison: eq
  Filter Value: "Office Locations"
  Permissions (denied): edit, create, delete

Analysts can view offices but not modify locations (read-only — read is not denied).

Combining Admin Rights + Role Restrictions

Default Behavior: All users can see everything but cannot alter anything (without admin rights).

Adding Write Access with Restrictions:

Example: Field workers can edit their own work but not others'

Admin Rights:
  - reportsCreate: true
  - reportsUpdate: true

Role Restrictions:
  Model: report
  Field: submittedBy
  Comparison: ne
  Filter Value: [current user ID]
  Permissions (denied): edit

Result:

• Workers can create reports (admin right granted)
• Workers can edit ONLY their own reports (role restriction filters out others)
• Cannot see or modify other workers' reports

Server-Side Enforcement

How It Works:

• All queries filtered before data is returned
• Role restrictions applied on the server (not just UI hiding)
• Users cannot bypass via direct API calls, browser tools, or exports
• Data truly doesn't exist for unauthorized users

Security Implications:

• Screenshot of someone else's screen won't help (data won't load for you)
• Cannot export restricted data (server enforces filters)
• Cannot "guess" record IDs (filtered before ID lookup)
• Records outside your permissions return as not found, even if you know the ID

Managing Roles

Creating Roles:

1. Navigate to Admin → Roles
2. Click "Create Role"
3. Enter role name
4. Add role restrictions (can have multiple)
5. Save

Creating a role requires the rolesCreate admin right.

Editing Roles:

• Requires the rolesUpdate admin right
• Can modify restrictions
• Can delete role with rolesDelete (frees members from those restrictions)

Roles have no member list to edit here — membership is set on the user, not on the role.

Role Membership:

• Membership lives on the user (user.roles); add or remove roles from a user's profile
• Users can be in multiple roles (restrictions combined)
• Leaving organization: Remove all roles from the user before deleting the account

Customizing Authorization for New Users

App Settings Configuration (Requires appSettingSchemasModify):

1. Navigate to App Settings
2. "Default Roles" - the roles auto-assigned to new accounts
3. Save

There is no "default admin rights" setting — new users start with no admin rights. Grant rights per user from their profile after the account is created.

Typical Configurations:

Field Worker:

• Default roles: ["Field Workers"]
• Admin rights granted on the user after creation: reportsCreate

Office Coordinator:

• Default roles: none
• Admin rights granted on the user after creation: workOrdersCreate, stockItemsCreate, stockItemsUpdate

No Auto-Grant (Manual Review):

• Default roles: none
• Admins manually assign roles and rights after account review.

Viewing Effective Permissions

For Specific User:

1. Navigate to user profile
2. "Admin Rights" section - What they CAN do
3. "Roles" section - What they CANNOT see (via restrictions)
4. Combined view shows effective permissions

Testing Permissions:

1. Login as user (or impersonate with admin permission)
2. Navigate normally
3. Restricted data simply doesn't appear
4. Actions without admin rights disabled/hidden

Best Practices

Start Restrictive, Grant as Needed:

• New users get minimal permissions
• Add admin rights as roles require
• Easier to grant than revoke (avoids "permission creep")

Use Roles for Data Visibility:

• Separate contractors (prevent competition intelligence)
• Separate work stages (QC from field workers)
• Separate asset types (infrastructure from active equipment)

Use Admin Rights for Capabilities:

• Who can create assignments
• Who can modify inventory
• Who can grant permissions

Document Role Purpose:

• Clear role name ("Contractor A" better than "Role 1")
• Description explains restrictions
• Helps future admins understand intent

Regular Permission Audits:

• Quarterly review user admin rights
• Remove unused rights (user changed roles)
• Check role memberships (users left organization)

Monitor Access Attempts:

• Log failed authorization attempts
• Pattern of denials = user trying unauthorized access
• Investigate and adjust permissions or educate user

Principle of Least Privilege:

• Grant minimum permissions required for job function
• Temporary elevated access for projects (remove after)
• Super rights (adminRightsModify) only to trusted admins