Data Access Rules

API Now! uses an Authorization Engine to evaluate whether an incoming request is allowed to read or write data. Access is governed by Access Rules that you attach to your API endpoints in the API Modeler.

Access Rule Inheritance

To prevent redundant configuration, access rules support hierarchical inheritance. An endpoint (action) inherits rules from its parent contexts in the following order:

graph TD
    API[1. API Level - Broadest Default] -->|Inherited by| Entity[2. Exposed Entity Level]
    Entity -->|Inherited by| Parent[3. Parent Exposed Entity Level]
    Parent -->|Inherited by| Action[4. Action Level - Most Specific]

Shadowing Policy (Specific-Over-General)

The authorization engine enforces a “Specific-Over-General” shadowing policy. If a rule of a specific type (for example, matchUserRole or allowAuthenticated) is defined on an Action, it completely shadows (overrides) any rule of that same type defined on the parent Exposed Entity or API Model.

This allows you to set broad security defaults (e.g. allowing all authenticated users to read records) and override them only for sensitive actions (e.g. restricting delete operations to administrators).

Mandatory vs. Permission Rules

When attaching access rules to an endpoint, you can configure whether each rule is Mandatory or acts as a Permission check. This controls how the engine evaluates multiple rules combined on the same endpoint.

Permission Rules (Default / OR Logic)

By default, rules act as permission checks. If you attach multiple permission rules to an endpoint, they operate with OR logic.

Behavior: If at least one permission rule evaluates to true (passes), access is granted.
Example: Attaching matchResourceOwner AND matchUserRole (with role ['admin']) as permission rules allows access if the user is the owner of the record OR if the user is an administrator.

Mandatory Rules (AND / Gatekeeper Logic)

When you mark a rule as Mandatory (mandatory: true), it acts as a strict gatekeeper that must be satisfied for the request to proceed.

Behavior: If any mandatory rule evaluates to false (fails), access is immediately denied, regardless of any other rules.
Example: If you want to ensure that only employees from a specific email domain can access the system, you can set matchEmailDomain (with domains ["company.com"]) as Mandatory. You can then use normal permission rules to specify which roles (e.g., admin or employee) can access specific endpoints. If a user has the admin role but their email is admin@gmail.com, they will be blocked because the mandatory domain check failed.

Key Takeaway

Mandatory Rules: Must all pass (all evaluate to true). One failure blocks the request.
Permission Rules: Only one needs to pass (at least one evaluates to true). If there are no permission rules configured, access is determined solely by the mandatory rules.

Standard Access Rule Types

You can configure several built-in access rules on your APIs.

Allow Public Access (`allowPublic`)

Allows any anonymous client to call the endpoint without logging in.

Allow Public Access Rule Configuration

Allow Authenticated Users (`allowAuthenticated`)

Restricts access to clients with a valid login session.

Allow Authenticated Users Rule Configuration

Match User Role (`matchUserRole`)

Restricts access to users holding specific permission roles (e.g., ['admin'] or ['manager']).

Match User Role Rule Configuration

Match Resource Owner (`matchResourceOwner`)

Restricts access to the specific user who owns the record.

This rule requires a ResourceOwnerIdentifier or RelationalResourceOwner semantic module to be attached to a property in the Data Domain.
For list actions, this automatically filters the database query so users only see their own records.
For detail actions (Read, Update, Delete), the server rejects the request if the record owner’s ID does not match the active login session ID.

Match Resource Owner Rule Configuration

Match Email Domain (`matchEmailDomain`)

Restricts access to users whose authenticated email address belongs to specific email domains (e.g., ["my-company.com"]). This is ideal for internal tools and business-to-employee apps.

Match Email Domain Rule Configuration

Match Resource Attribute (`matchResourceAttribute`)

Restricts access based on the value of a property on the resource itself. For example, you can allow a Read action only if a record’s status attribute equals "published". It supports standard operators: equal, notEqual, startsWith, endsWith, contains, greaterThan, lessThan, greaterThanOrEqual, and lessThanOrEqual.

Match Resource Attribute Rule Configuration

Lifecycle Status (`lifecycleStatus`)

A specialized rule for entities utilizing Status Semantics. It allows you to specify a list of allowedStatuses or deniedStatuses (e.g., preventing access to "Draft" or "Archived" records). Because an entity can have at most one Status semantic, the engine automatically knows which column to evaluate.

Lifecycle Status Rule Configuration

Match Organization (`matchOrganization`)

Restricts access to users who are active members of the organization that owns the resource.

This rule is designed to secure multi-tenant path routing, such as /orgs/{orgId}/projects/{projectId}/tasks/{taskId}.
The Serverless Engine automatically extracts the organization ID from the path parameters (e.g., {orgId}) and verifies that the authenticated user has a membership link to that organization (defined by the OrganizationMembers semantic).
Allowed Org Roles (allowedOrgRoles): An optional array of roles (e.g., ['admin', 'editor']) to restrict access to specific membership roles within the organization. If omitted or empty, any active member of the organization is permitted access.

Practical Security Scenarios

When configuring your API, you will typically mix and match these rules to fit your business requirements. Here are the most common scenarios:

Scenario 1: Public Blog or Product Catalog

The Goal: Anyone can browse articles or products, but only logged-in team members can create or modify them.
How to configure:
- On the List and Read actions, set Allow Public Access (allowPublic).
- On the Create, Update, and Delete actions, set Allow Authenticated Users (allowAuthenticated) or restrict them to specific roles using Match User Role (matchUserRole).

Scenario 2: Personal Dashboard (To-Dos, Notes, Invoices)

The Goal: Users must log in, and they should only be able to view, edit, or delete their own data. They should never see notes or invoices belonging to another user.
How to configure:
- At the Exposed Entity level, set Match Resource Owner (matchResourceOwner).
- How it behaves: If User A calls GET /notes, the Serverless Runtime automatically adds a filter so they only retrieve User A’s notes. If they try to request GET /notes/99 (where note 99 belongs to User B), the server automatically returns a 403 Forbidden error.

Scenario 3: Manager Overrides (Internal HR or Support Portal)

The Goal: Regular employees can see and manage their own expense reports, but managers and admins must be able to view and manage all employees’ reports.
How to configure:
- Attach both Match Resource Owner (matchResourceOwner) and Match User Role (matchUserRole configured with ['manager', 'admin']) rules to the Expense Reports entity.
- How it behaves: The Authorization Engine checks if the user is the owner or if they hold a privileged role. If either check passes, access is granted.

Scenario 4: Strict Administration Console

The Goal: Only system administrators can delete accounts, change system settings, or view system audit logs.
How to configure:
- On these entities or sensitive actions (like Delete user), set Match User Role (matchUserRole) specifying ['admin'].
- All other users (even standard authenticated users) will be blocked.