Match Resource Owner

The Match Resource Owner (matchResourceOwner) access rule restricts API operations based on direct resource ownership. It ensures that users can only access or modify records that belong to them (or their own user account record).

---

1. How It Works

• Direct Ownership Verification: The engine evaluates whether the authenticated caller’s User ID matches the owner field of the resource.
• Automatic Collection Scoping (FETCH): On list, search, and restore queries, the engine automatically injects a WHERE owner_id = :userId clause into the database query so users only retrieve their own records.
• Pre-Execution Detail Checks (PRE_FETCH): On read, update, and delete actions, the engine checks ownership before executing the operation.
• Inherited vs. Direct Ownership: Match Resource Owner handles direct ownership (a direct link to User or the User entity itself). If ownership is inherited through a parent or ancestor entity (e.g. a comment owned via an article), use Match Relational Resource Owner instead.

Property	Specification
Rule Type	matchResourceOwner
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 Phases	FETCH (list, search, restore), PRE_FETCH (read, update, delete, link, unlink)

---

2. How Ownership Is Resolved

When you add Match Resource Owner to an Access Scenario, the platform automatically resolves how ownership is verified based on the entity:

1. Direct Association to User (ResourceOwnerIdentifier)

For standard resource entities (e.g. Article, Project, Invoice, TimeLog):

• The resource entity must have a direct association pointing to the User entity.
• This association must be annotated with the ResourceOwnerIdentifier semantic module in your Data Domain.
• The platform automatically detects this annotated association to resolve the owner foreign key column (e.g. author_id, user_id, client_id).

Runtime Behavior:

• Collection Queries (list, search, restore) in FETCH Phase: Automatically injects WHERE <owner_id> = :current_user_id into the SQL query so callers only receive their own records.
• Single-Record Actions (read, update, delete) in PRE_FETCH Phase: Executes a targeted database check ensuring the requested record ID belongs to :current_user_id before executing the action.

---

2. The User Entity Itself (Self-Profile Actions)

When the rule is applied directly to the User entity:

• Explicit ID Endpoints (GET /users/:id, PATCH /users/:id): The platform automatically recognizes that the resource being operated on is the user record itself. Ownership is evaluated in-memory during PRE_FETCH by verifying that the route parameter matches the authenticated caller’s User ID (String(params.id) === String(currentUser.id)).
• Current User Endpoints (GET /users/me, PATCH /users/me): When using a Current User (/me) exposure, the runtime automatically injects the authenticated User ID into the query. The invariant scenario automatically applies Allow Authenticated and Match Resource Owner (target: 'user-entity') without requiring explicit route parameter validation.

---

3. Important: How Creation Actions Work

create Actions Do Not Use Match Resource Owner

Match Resource Owner cannot be used on create (POST) actions because the record does not exist in the database prior to execution.

How creation is handled instead:

1. Gate the create action using Allow Authenticated or Match User Role.
2. Tag the owner foreign key in your Data Domain with the ResourceOwnerIdentifier semantic module.
3. The platform will automatically populate the owner foreign key with the authenticated user’s ID upon creation. Any values submitted in the POST request body for this foreign key are ignored—the authenticated user from the session is always assigned as the owner to prevent spoofing.

---

4. Prerequisites in the Data Domain

• User Entity Endpoints: The entity must be annotated with the User semantic module.
• Resource Entity Endpoints: The target entity must have an association pointing to the User entity, annotated with the ResourceOwnerIdentifier semantic module.

---

5. Recommended Modeling Patterns

Pattern 1: User Self-Profile Management (/users/me vs /users/:id)

You can model user profile management in two ways depending on whether your API needs to expose user IDs in URLs:

Option A: Dedicated /users/me Singleton (Recommended)

Using a Current User (/me) exposure, users interact exclusively with their own profile at /users/me. The runtime resolves the user’s ID directly from their session token:

GET    /users/me   --> Returns authenticated user's own profile (200 OK)
PATCH  /users/me   --> Updates authenticated user's own profile (200 OK)
DELETE /users/me   --> Deletes authenticated user's own account (204 No Content)

Option B: Explicit Parameterized Routes (/users/:id)

If your API exposes public or admin /users/:id endpoints, use Match Resource Owner: user-entity on mutation actions to restrict profile updates to the record owner:

graph LR
    subgraph "User Entity Actions (/users/:id)"
        Read["GET /:id (Read)"] -->|Allow Authenticated| LoggedIn["Any Logged-in User"]
        Update["PATCH /:id (Update)"] -->|Match Resource Owner: user-entity| Self["Owner Only (Self)"]
        Delete["DELETE /:id (Delete)"] -->|Match User Role: admin| Admin["Admins Only"]
    end

---

Pattern 2: Creator-Owned Content with Admin Override (target: 'association')

Allow users to manage their own content while giving administrators full management override:

Article.update Scenarios:
├── Scenario 1 (Admin Override):
│   └── Match User Role: ['admin']                      <- Evaluated 1st: Admins can edit any article
└── Scenario 2 (Author Self-Management):
    ├── Allow Authenticated                             <- Evaluated 2nd: Must be logged in
    └── Match Resource Owner (author)                   <- Must be the article's direct author

---

6. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match Resource Owner	401 Unauthorized
Caller is Resource Owner	User’s ID matches the resource’s owner foreign key (or user PK)	200 OK / 204 No Content
Caller is NOT Resource Owner	User’s ID does not match the resource owner	403 Forbidden
Resource Does Not Exist	ID provided in path does not exist in database	404 Not Found

---

Next Steps

• Match Relational Resource Owner: Inherit ownership from a parent or ancestor entity in the URL hierarchy.
• Match Resource Attribute: Restrict operations based on properties of the target record.
• Resource Owner Identifier Semantic: Data modeling reference for tagging ownership associations.