Access Control

Alpha uses a layered access control system that combines role-based permissions with resource-level access controls. This allows fine-grained control over what users can see and do within the system.

Access Control Layers

Alpha's access control system has three layers:

Full Access

Users with Full Access can access all subsidiaries and projects without explicit assignment.

What Full Access Means

Full Access is granted in any of three ways. The backend treats all three as equivalent for resource-scoping checks (see AccessControlService.hasFullAccess()):

Any of these grants:

• Access to all subsidiaries (bypasses canAccessSubsidiary)
• Access to all projects (bypasses canAccessProject)

Full Access vs Tenant Admin

The Full Access flag and the Tenant Admin permission are functionally equivalent in the backend for resource-scoping checks. They are kept separate so that:

• A user can be granted broad resource access (Full Access flag) without being given administrative permissions like managing other users or roles
• Administrative roles (Tenant Admin) automatically get full resource access without needing the flag toggled separately

When Full Access Applies

• Users with the Tenant Admin permission automatically have full access
• Administrators can grant full access independently via the user's access settings (this sets the hasFullAccess flag without granting administrative permissions)

Managing Full Access

1. Go to Administration > Users
2. Open the user
3. Click Manage Access
4. Toggle Full Access on or off

Subsidiary Access

Subsidiary access controls which business entities a user can work with.

How Subsidiary Access Works

Users without full access must be explicitly granted access to subsidiaries. Subsidiary access has an important characteristic: hierarchical inheritance.

Access Inheritance

Subsidiaries can be organized in a parent-child hierarchy. When a user has access to a parent subsidiary, they automatically gain access to all its children.

Parent Company (access granted)
├── Division A (inherited access)
│   ├── Branch 1 (inherited access)
│   └── Branch 2 (inherited access)
└── Division B (inherited access)
    └── Branch 3 (inherited access)

In this example, granting access to "Parent Company" gives the user access to all six entities.

Direct vs Inherited Access

When viewing users with subsidiary access, inherited access is indicated with a badge showing which parent it was inherited from.

Granting Subsidiary Access

From the User

1. Go to Administration > Users
2. Open the user
3. Click Manage Access
4. Go to the Subsidiary Access tab
5. Select subsidiaries from the tree view
6. Save

From the Subsidiary

1. Go to Administration > Subsidiaries
2. Open the subsidiary
3. Click Manage Users
4. Add or remove users
5. Save

Access Inheritance Behavior

When you grant access to a parent:

• Child subsidiaries become accessible automatically
• Child subsidiaries appear disabled in the selection (cannot be individually toggled)
• Removing parent access removes access to all children (unless directly assigned)

Subsidiary Access Examples

Example 1: Regional Manager

A regional manager needs access to all branches in their region:

• Grant access to the regional parent subsidiary
• All branches inherit access automatically
• New branches under that region automatically accessible

Example 2: Branch-Specific User

A warehouse user only works at one location:

• Grant access only to their specific branch
• They cannot see other branches or the parent

Project Access

Project access controls which construction projects a user can view and work with.

How Project Access Works

Unlike subsidiaries, projects do not have hierarchical inheritance. Each project must be explicitly assigned to users who need access.

Granting Project Access

From the User

1. Go to Administration > Users
2. Open the user
3. Click Manage Access
4. Go to the Project Access tab
5. Select projects from the list
6. Save

From the Project

1. Open the project
2. Click Manage Access
3. Add or remove users
4. Save

Project Access Examples

Example 1: Project Manager

A project manager oversees three specific projects:

• Grant access to each of the three projects individually
• They can only see and manage those projects

Example 2: Company-Wide Viewer

A finance user needs to see all projects for reporting:

• Grant Full Access instead
• Or grant access to each project as needed

Access Control Best Practices

Design Principles

Common Patterns

Department-Based Access

Company
├── Sales Division (Sales team access)
├── Operations Division (Operations team access)
└── Finance Division (Finance team access)

Region-Based Access

Company
├── North Region (Regional staff access)
├── South Region (Regional staff access)
└── Central Region (Regional staff access)

Project-Based Teams

For project teams:

• Create a role with appropriate permissions
• Assign the role to team members
• Grant project access to each team member

Access Auditing

Regular access reviews should verify:

• Users have appropriate access for their current role
• Former employees are deactivated
• Project access is removed when projects complete
• Subsidiary access matches current responsibilities

Combining Roles and Access

Access is determined by the combination of roles and resource access:

Example:

A user with:

• READ_PRODUCTS permission
• Access to Subsidiary A only

Can:

• View products in Subsidiary A

Cannot:

• View products in Subsidiary B (no access)
• Create products anywhere (no permission)

Troubleshooting Access Issues

User Can't See a Subsidiary

1. Check if user has subsidiary access (direct or inherited)
2. Check if user has full access
3. Verify user status is Active

User Can't See a Project

1. Check if user has project access
2. Check if user has full access
3. Verify user has appropriate role permissions

User Can See But Can't Edit

1. Check role permissions
2. User may have access but lack edit permissions

User Has Full Access But Button Is Disabled

A user with the Full Access flag may still see specific action buttons greyed out. This happens when a UI permission gate checks for the explicit Tenant Admin permission rather than calling the backend's hasFullAccess() helper.

Known examples:

• Approve stock transfer — gated on TENANT_ADMIN in the UI, even though the backend only requires UPDATE_INVENTORY. A user with Full Access plus UPDATE_INVENTORY would be allowed by the API but cannot trigger it from the UI.

Workarounds:

• Assign the user a role that includes the Tenant Admin permission (e.g. BK_ADMIN for Burger King), or
• Have a user that already holds Tenant Admin perform the action

If you encounter this on a screen not listed above, report it — the UI gate should be aligned with the backend check.

Related