Authorization Getting Started

API Now! provides a visual, declarative authorization engine designed to make securing your APIs intuitive and robust—without writing backend code.

Instead of writing complex conditionals or database queries to verify permissions, you model your security using Access Scenarios.

---

1. What is an Access Scenario?

An Access Scenario represents a distinct user persona and its access policy. It defines who the caller is and what conditions must be met for them to access data.

For example, when exposing an Article entity in your API, you might have three distinct personas:

1. Administrators: Can view, edit, and delete all articles regardless of status.
2. Authors: Can view, edit, and manage their own articles (drafts and published).
3. Public Readers: Can only view published articles.

Each persona is modeled as its own self-contained Access Scenario.

graph TD
    subgraph "Access Scenarios (Evaluated in Priority Order)"
        S1["Scenario 1: Administrator<br/>(Match User Role: admin)"]
        S2["Scenario 2: Article Author<br/>(Allow Authenticated + Match Resource Owner)"]
        S3["Scenario 3: Public Reader<br/>(Allow Public + Lifecycle Status: Published)"]
    end

Identity Rules vs. Data-Scoping Rules

Every Access Scenario consists of two types of rules:

1. Identity-Constraining Rules (WHO): Identifies who the caller is before touching any data. Examples include Allow Public, Allow Authenticated, Match User Role, or Match Organization Role.

   Rule Requirement

   Every Access Scenario must contain at least one Identity-Constraining rule. The platform enforces this validation rule automatically so that endpoints are never left unintentionally unprotected.

2. Data-Scoping Rules (WHAT): Determines what records the caller can see or interact with. Examples include Match Resource Owner, Lifecycle Status, or Match Resource Attribute.

---

2. How Rules and Scenarios are Evaluated

The authorization engine uses a simple, predictable evaluation logic based on AND and OR principles:

Evaluation Level	Logic	Description
Inside a Single Scenario	AND	All rules within the scenario must pass. If a scenario requires Allow Authenticated AND Match Resource Owner, a caller must satisfy both conditions.
Between Multiple Scenarios	OR (Priority Order)	Scenarios are evaluated top-to-bottom. The engine checks each scenario in order. The first scenario whose conditions are completely met grants access.

The Evaluation Flow

When a client sends a request to an endpoint:

1. Identity Pre-Check: The engine evaluates the identity rules of each scenario in priority order to identify all matching personas.
2. First Match Wins: For the first matching scenario that satisfies all conditions, access is granted and its data filters are applied.
3. Rejection by Default: If none of the configured scenarios pass, the request is rejected immediately (401 Unauthorized for unauthenticated callers, or 403 Forbidden for logged-in users).

---

3. The Scenario Hierarchy (API, Entity, and Action Levels)

To prevent repetitive configuration, you can attach Access Scenarios at three different levels of your API Model:

graph TD
    API["1. API Model Level<br/>(Global baseline defaults)"] -->|Inherited by| Entity["2. Exposed Entity Level<br/>(Applies across all actions of an entity)"]
    Entity -->|Inherited by| Action["3. Action Level<br/>(Highest priority: specific endpoint rules)"]

Concatenation Order

When an action executes, the authorization engine merges scenarios from all three levels in order of specificity:

$\text{Effective Scenarios} = \text{Action Scenarios} \longrightarrow \text{Entity Scenarios} \longrightarrow \text{API Model Scenarios}$

1. Action Level (Evaluated first / Highest priority): Endpoint-specific scenarios (e.g., custom rules for DELETE /articles/:id).
2. Exposed Entity Level (Evaluated second / Medium priority): Common scenarios shared across all operations on that entity (e.g., default access for /articles).
3. API Model Level (Evaluated last / Lowest priority): Global baseline scenarios that apply across your entire API unless handled earlier.

Isolating Sensitive Endpoints (“Override Parent Scenarios”)

Sometimes an individual action needs strict security that should not inherit broader parent policies. For example, you might allow general users to read articles at the entity level, but you want the DELETE action to strictly require an Administrator role.

In the action settings, you can check “Override parent scenarios”:

• When disabled (default): The action evaluates its own scenarios first, then falls back to entity-level and API-level scenarios.
• When enabled: The action ignores all entity and API-level scenarios. Only the scenarios explicitly defined on this action are evaluated.

---

4. Ordering Your Scenarios: Specific First, Broad Last

Because scenarios are evaluated in top-to-bottom priority order, the order of your scenarios matters.

Always order your scenarios from most specific (narrow persona) to most general (broad persona):

✅ Correct Order:
1. Scenario A: Administrator (Match User Role: admin)      <- Specific / Privileged
2. Scenario B: Author (Allow Authenticated + Owner)         <- Specific / Scoped
3. Scenario C: Public Reader (Allow Public + Published)     <- Broad / Catch-all

Avoid Broad-Before-Narrow Traps

If you place a broad scenario like Allow Public at the top, it will match every incoming request first. As a result, the engine will never evaluate the specialized scenarios below it.

API Now! includes a built-in validation warning (ACTION_SCENARIO_BROAD_BEFORE_NARROW) that alerts you if a broad rule appears before a narrower role or ownership rule.

---

5. How Scenarios Work on Single Records vs. Lists

Understanding how the engine handles single-record lookups versus collection queries helps you design clean data experiences for your users.

Single-Record Actions (read, update, delete)

For single-resource endpoints (e.g., GET /articles/42):

• The engine loads the requested record and checks your scenarios in order (Priority Fallthrough).
• If Scenario 1 (Author) fails because you are not the author, the engine moves to Scenario 2 (Public Reader).
• If Scenario 2 passes because the article is marked published, access is granted with 200 OK.
• If no scenario matches the record, the engine returns 403 Forbidden (or 404 Not Found if the record does not exist).

Collection Actions (list, search)

For collection endpoints (e.g., GET /articles):

• The engine determines your highest-priority matching persona and applies its query filter (First-Match-Wins).
• It does not merge multiple scenarios into an arbitrary database OR union. This guarantees optimal database indexing, fast response times, and accurate pagination counts (meta.total, page, per_page).

Product Modeling Recommendation: Dedicated Sub-Resources

To provide both a personal author workspace and a public catalog, follow standard REST sub-resource modeling:

1. Personal Workspace (GET /users/:userId/articles):
   • Model as a nested sub-resource under User.articles.
   • Configure with: [Allow Authenticated, Match Resource Owner].
   • The user sees all their own drafts, published posts, and archived articles.
2. Public Catalog (GET /articles):
   • Model as a top-level catalog endpoint.
   • Configure with: [Allow Public, Lifecycle Status: Published].
   • Any client sees only the public published articles.

---

6. Practical Real-World Examples

Here are three common patterns to reference when designing your API authorization:

Example 1: Editorial Publishing Platform

• Goal: Admins manage everything, authors edit their own submissions, and public visitors read published posts.
• Scenarios configured on Article:
  • Scenario 1 (Admin): Match User Role: ['admin', 'editor'] (Unfiltered access).
  • Scenario 2 (Author Workspace): Allow Authenticated + Match Resource Owner: author (Own records).
  • Scenario 3 (Public Readers): Allow Public + Lifecycle Status: ['published'] (Published records only).

Example 2: Multi-Tenant Team Collaboration

• Goal: Organization members can collaborate on team projects, while guests only view shared items.
• Scenarios configured on Project:
  • Scenario 1 (Team Members): Match Organization Role: ['owner', 'admin', 'member'].
  • Scenario 2 (External Guests): Allow Authenticated + Match Resource Attribute: visibility == 'shared'.

Example 3: Secure User Profiles

• Goal: Users can update their own account details, but cannot edit other users’ profiles.
• Scenarios configured on User Update action:
  • Scenario 1 (Admin Override): Match User Role: ['admin'].
  • Scenario 2 (Self Update): Allow Authenticated + Match Resource Owner: self.
  • Action Setting: Enable “Override parent scenarios” so general read rules don’t permit unauthorized profile changes.

---

Next Steps

Now that you understand the core concepts of Access Scenarios, explore the rest of the authorization guides:

• Supported Authorization Strategies: Discover RBAC, Organization RBAC, and Enterprise RBAC models.
• Access Rules Reference: Learn how to configure individual identity and data-scoping rules.