Match User Role

The Match User Role (matchUserRole) access rule restricts API endpoints based on the authenticated user’s global role.

It is the core building block for Role-Based Access Control (RBAC), enabling you to grant access to specific roles (e.g., admin, editor, viewer), enforce minimum privilege tiers, or block restricted user types.

1. How It Works

When a request is received, Match User Role evaluates the user’s role from their active session:

Who is evaluated: Authenticated users holding a valid role.
Anonymous callers: Automatically rejected with 401 Unauthorized.
Unauthorized roles: Rejected with 403 Forbidden.
Performance: Evaluates in-memory during the identity pre-check phase (PRE_FETCH) without requiring database queries.

Property	Specification
Rule Type	`matchUserRole`
Supported Strategies	`RBAC`, `EnterpriseRBAC` (Not available in `OrganizationRBAC`)
Allowed Placement Levels	Global API Model Level, Exposed Entity Level, Action Level
Execution Phase	`PRE_FETCH` (Immediate in-memory evaluation)

2. Prerequisites in the Data Domain

To use Match User Role, your Data Domain must configure:

User: A designated User Entity.
UserRole: An enum property on the User entity defining the allowed roles (e.g., ['viewer', 'editor', 'admin']).
Session Mapping: The role property must be mapped in your API Model’s Session Configuration so it is available in the user session.

3. The Four Matching Modes

Match User Role supports four flexible matching modes:

1. Allowlist (`allowlist`) — Default

Access is granted only if the user’s role is included in the Allowed Roles list.

Example: allowed: ['admin', 'editor']
Behavior: Users with the role admin or editor are permitted. All other roles are denied.

2. Denylist (`denylist`)

Access is granted to all authenticated users except those in the Denied Roles list.

Example: denied: ['suspended', 'guest']
Behavior: Blocks suspended accounts and guests while granting access to all standard user roles.

3. Minimum Role (`minRole`)

Requires the user’s role to meet or exceed a Minimum Role tier in your role hierarchy.

Example: minimumRole: 'editor' (where hierarchy is viewer < author < editor < admin)
Behavior: Both editor and admin users are granted access. viewer and author users are denied.

4. Maximum Role (`maxRole`)

Restricts access to users at or below a Maximum Role tier.

Example: maximumRole: 'viewer'
Behavior: Grants access to viewer accounts while blocking elevated roles (useful for customer-only surveys or onboarding flows).

4. The Role Hierarchy Contract (Ascending Privilege Order)

When using Minimum Role (minRole) or Maximum Role (maxRole), the platform determines role hierarchy based on the order roles are declared in your UserRole enum property.

Role Ordering Rule

Always define your role enum values in ascending order of privilege (from lowest privilege to highest privilege):

Index 0: viewer       (Lowest privilege)
Index 1: author
Index 2: editor
Index 3: admin        (Highest privilege)

Because minRole and maxRole use the list position to evaluate hierarchy, reordering the enum in the Data Modeler will change your role tier boundaries.

5. Multi-Role Evaluation Strategy (`roleMatch`)

In your Data Domain, you can configure the UserRole property as a multi-value field (multiple: true), allowing a user to hold an array of roles simultaneously (e.g., ['editor', 'billing_manager'] or ['editor', 'auditor']).

How `roleMatch` Affects Evaluation

When users hold multiple roles, the Role Match Strategy (roleMatch: 'any' | 'all') controls how their roles are tested:

roleMatch: 'any' (Default): Evaluates with OR logic. Access is granted if the user holds at least one of the permitted roles.
roleMatch: 'all': Evaluates with AND logic. In allowlist mode, the user must hold all of the specified roles simultaneously (having additional enterprise roles is permitted).

Single-Role vs. Multi-Role Behavior in Allowlist Mode

Given a rule configured with allowed: ['editor', 'admin']:

With roleMatch: 'any' (Default):
- User with single role 'editor' $\rightarrow$ Passes (matches 'editor').
- User with multi-role ['editor', 'sales_rep'] $\rightarrow$ Passes (matches 'editor').
- User with multi-role ['viewer', 'sales_rep'] $\rightarrow$ Fails (holds neither 'editor' nor 'admin').
With roleMatch: 'all':
- User with single role 'editor' $\rightarrow$ Fails (missing the 'admin' role).
- User with multi-role ['editor', 'admin', 'sales_rep'] $\rightarrow$ Passes (holds both 'editor' and 'admin').
- User with multi-role ['editor', 'sales_rep'] $\rightarrow$ Fails (missing the 'admin' role).

Behavior Across All Matching Modes

Mode	`roleMatch: 'any'` (Default)	`roleMatch: 'all'`
Allowlist (`allowlist`)	Passes if the user holds at least one role in `allowed`.	Passes only if the user holds all roles in `allowed`.
Denylist (`denylist`)	Denies access if any role is in `denied` (Secure Default).	Denies access only if all roles held by the user are in `denied`.
Minimum Role (`minRole`)	Passes if the user’s highest role meets or exceeds `minimumRole`.	Passes only if all held roles meet or exceed `minimumRole` (lowest role $\ge$ min).
Maximum Role (`maxRole`)	Passes if at least one held role is $\le$ `maximumRole`.	Passes only if all held roles are $\le$ `maximumRole` (highest role $\le$ max).

Concrete Examples & Important Security Implications

1. Allowlist Example: `allowed: ['editor', 'admin']`

With roleMatch: 'any': User with ['editor', 'sales_rep'] is Granted because they have 'editor'.
With roleMatch: 'all': User with ['editor', 'sales_rep'] is Denied because they lack 'admin'. User with ['editor', 'admin', 'sales_rep'] is Granted.

2. Denylist Example: `denied: ['suspended', 'guest']`

3. Minimum Role Example: `minimumRole: 'editor'`

(Enum order: viewer < author < editor < admin)

User holds: ['viewer', 'editor']
- With any: Granted (the user’s highest role editor satisfies $\ge$ editor).
- With all: Denied (the user also holds viewer, which is below the editor threshold).

4. Maximum Role Example: `maximumRole: 'viewer'`

User holds: ['viewer', 'admin']
- With any: Granted (user holds viewer which satisfies $\le$ viewer).
- With all: Denied (user also holds admin which exceeds the viewer limit).

6. Recommended Modeling Patterns

Pattern 1: Restricting Sensitive Operations to Administrators

To protect administrative endpoints (such as deleting accounts or modifying system settings), configure an allowlist scenario on the sensitive action:

graph LR
    subgraph "User Entity Actions"
        Read["GET /users/:id (Read)"] -->|Scenario: Allow Authenticated| LoggedIn["All Logged-in Users"]
        Delete["DELETE /users/:id (Delete)"] -->|Scenario: Match User Role| Admin["Admins Only"]
    end

Pattern 2: Tiered Content Operations (Admin Override + Author Ownership)

Combine Match User Role and Match Resource Owner in separate scenarios to allow administrators to edit any article while authors can only edit their own submissions:

Article.update Scenarios:
├── Scenario 1 (Staff Management):
│   └── Match User Role: ['editor', 'admin']          <- Evaluated 1st: Staff can update any article
└── Scenario 2 (Author Self-Service):
    ├── Allow Authenticated                           <- Evaluated 2nd: Verified author
    └── Match Resource Owner (author)                  <- In-memory check: Caller must be author

7. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint protected with `Match User Role`	`401 Unauthorized`
Logged-in with Allowed Role	User role matches criteria (e.g. `admin`)	`200 OK` / `204 No Content`
Logged-in with Disallowed Role	User role fails criteria (e.g. `viewer` trying to delete)	`403 Forbidden`

Next Steps

Match Organization Role: Role checks within multi-tenant organizations.
Match Project Role: Role checks within project teams.
Match Resource Owner: Author and creator ownership access control.