Match Path Parameter

The Match Path Parameter (matchPathParameter) access rule grants access if one or more URL path parameters match properties on the authenticated user’s session.

It is the fastest identity-gating rule in the system: a pure, in-memory string comparison evaluated during the PRE_FETCH phase with zero database queries. It is ideal for self-service user hierarchies (such as /users/:userId/... or /@:username/...) where callers should only ever access their own URL paths.

---

1. How It Works

• Pure In-Memory Evaluation: Compares the URL parameter against the session property in memory before any database queries execute.
• Full Ancestor Chain Awareness: Path parameters are resolved from the entire URL hierarchy. For deeply nested routes (e.g. /users/:userId/accounts/:accountId/transactions), matchPathParameter can validate :userId regardless of how many nesting levels deep the resource is.
• AND-Logic Multi-Mapping: If multiple parameter mappings are configured, all mappings must match for access to be granted.

Property	Specification
Rule Type	matchPathParameter
Supported Strategies	All strategies (RBAC, OrganizationRBAC, EnterpriseRBAC)
Allowed Placement Levels	Exposed Entity Level (exposure), Action Level (action) (Not allowed at global API Model Level)
Execution Phase	PRE_FETCH across all action kinds (list, read, create, update, delete, link, unlink)

---

2. Configuration Options

When configuring Match Path Parameter in the API Modeler, you define one or more Parameter Mappings:

Configuration Field	Description	Example
Path Parameter (pathParameter)	The name of the parameter in the route URL path.	userId, username, accountId
Session Property (sessionProperty)	The property on the authenticated user’s session.	id, username, account_id

Multi-Mapping Example

If you configure:

1. pathParameter: 'userId' $\rightarrow$ sessionProperty: 'id'
2. pathParameter: 'tenantId' $\rightarrow$ sessionProperty: 'organization_id'

Both :userId and :tenantId in the URL must match the caller’s session values for the request to pass.

---

3. Prerequisites in the Data Domain & Session Configuration

1. Path Parameter in Route: The route (or one of its parent segments) must define the specified path parameter.
2. Configured in Session Definition Properties: The property mapped in sessionProperty (e.g. id, username) must be included in Session Definition Properties in the API Modeler so it is hydrated onto the authenticated user object.

---

4. Recommended Modeling Patterns

Pattern 1: User-Isolated Self-Service APIs (/users/:userId/...)

In personal finance, healthcare, or private consumer applications, every endpoint is nested under the user’s ID:

graph LR
    subgraph "Personal Finance App URL Structure"
        User["/users/:userId (Profile)"]
        User --> Accounts["/users/:userId/accounts"]
        Accounts --> Tx["/users/:userId/accounts/:accountId/transactions"]
        User --> Budgets["/users/:userId/budgets"]
    end

• Attach Match Path Parameter (pathParameter: 'userId', sessionProperty: 'id') to the Exposed Entity level of User, Account, Transaction, and Budget.
• Zero Database Overhead: If User 123 attempts to call /users/456/accounts, the engine immediately rejects the request with 403 Forbidden without touching the database.

---

Pattern 2: Username-Anchored Routes (/@:username/...)

If your application uses public-facing vanity usernames in URLs (like GitHub or social media platforms):

• Map pathParameter: 'username' to sessionProperty: 'username'.
• The engine verifies that String(params.username) === String(currentUser.username).

---

Pattern 3: Staff Override + User Path Parameter Match

Allow administrators to manage any user account while restricting standard users to their own path:

Account.list Scenarios (/users/:userId/accounts):
├── Scenario 1 (Admin Support Staff):
│   └── Match User Role: ['support_admin', 'admin']    <- Staff can view accounts for any :userId
└── Scenario 2 (Account Owner Self-Service):
    ├── Allow Authenticated
    └── Match Path Parameter: userId == session.id     <- User can only view their own accounts

---

5. HTTP Status Codes Summary

Caller State	URL Request	Resulting HTTP Status
Anonymous (No token)	GET /users/123/accounts	401 Unauthorized
Matching User ID	User 123 calls GET /users/123/accounts	200 OK / 201 Created
Mismatched User ID	User 123 calls GET /users/456/accounts	403 Forbidden
Missing Session Property	Property mapped in rule is not in Session Definition Properties	403 Forbidden

---

Next Steps

• Match Resource Owner: Direct ownership checks for unnested or flat endpoints.
• Match Relational Resource Owner: Inheriting ownership from parent entities in nested routes.
• Session Configuration Guide: Managing session definition properties in the API Modeler.