Match Organization Role

The Match Organization Role (matchOrganizationRole) access rule restricts API operations based on the user’s membership and role within a specific Organization (Tenant).

In multi-tenant B2B applications (such as SaaS platforms, team collaboration tools, and client portals), permissions are contextual: a user might be an owner in their own organization, but only a viewer or guest in another. Match Organization Role ensures users can only access data belonging to organizations they are members of, with the appropriate tenant-level permissions.

---

1. How It Works

When a client calls an organization-scoped endpoint (such as /organizations/:orgId/dashboards):

• Tenant Identification: The engine extracts the organization ID from the route path parameter (:orgId).
• Membership Verification: The engine checks whether the authenticated user has an active membership in that organization.
• Role Check (Optional): If specific roles are configured, the engine verifies that the user holds one of the permitted organization roles.
• Automatic Tenant Filtering: For list queries, the engine automatically injects database filters so users only retrieve records belonging to the active organization.

Property	Specification
Rule Type	matchOrganizationRole
Supported Strategies	OrganizationRBAC, EnterpriseRBAC (Not available in standard RBAC)
Allowed Placement Levels	Exposed Entity Level, Action Level (Not allowed at global API Model Level)
Execution Phases	PRE_FETCH (mutations), FETCH (collection queries), POST_FETCH (single-record detail actions)

---

2. Prerequisites in the Data Domain

To use Match Organization Role, your Data Domain must define the following semantic models:

1. Organization: An entity representing the tenant organization.
2. User: An entity representing system users.
3. OrganizationMembers: A many-to-many (multiple: true) association connecting Organization to User.
4. OrganizationRole: An enum property attached to the OrganizationMembers association defining tenant roles (e.g., ['viewer', 'analyst', 'editor', 'admin', 'owner']).
5. OrganizationResource: A one-to-many association from Organization to each tenant-scoped sub-resource (e.g. Organization.dashboards).

---

3. Configuration Options

When attaching Match Organization Role to an Access Scenario in the API Modeler, you configure:

• Allowed Organization Roles (roles): A list of tenant roles permitted to execute this action (e.g., ['admin', 'owner']).
  • Configured with specific roles: Access is granted only if the user is a member AND holds one of the specified roles in that organization.
  • Left empty / Unspecified: Any active member of the organization is granted access, regardless of their role.

---

4. How It Operates Across Route Types

Top-Level Organization Routes (GET /organizations)

When listing organizations directly, the engine queries the membership join table and automatically returns only the organizations where the authenticated user is an active member (matching any configured role criteria).

Nested Sub-Resource Routes (GET /organizations/:orgId/projects)

When accessing resources nested under an organization:

1. The engine extracts :orgId from the route.
2. It verifies the user’s membership and role in that organization.
3. It automatically applies WHERE organization_id = :orgId to the database query, guaranteeing strict tenant isolation.

---

5. Recommended Modeling Patterns

Pattern 1: Tenant Member Read / Admin Manage

A standard SaaS model where all organization members can view shared resources, but only managers can create, update, or delete them:

graph TD
    subgraph "Dashboard Entity (/organizations/:orgId/dashboards)"
        List["GET (List)"] -->|Match Org Role: Any Member| M1["All Org Members"]
        Read["GET /:id (Read)"] -->|Match Org Role: Any Member| M2["All Org Members"]
        Create["POST (Create)"] -->|Match Org Role: admin, owner| Adm1["Org Admins Only"]
        Update["PATCH /:id (Update)"] -->|Match Org Role: admin, owner| Adm2["Org Admins Only"]
        Delete["DELETE /:id (Delete)"] -->|Match Org Role: owner| Own["Org Owner Only"]
    end

---

Pattern 2: Self-Service Organization Creation

To allow any registered user to bootstrap a new organization:

• On POST /organizations (Create): Use Allow Authenticated. Any logged-in user can create an organization.
• Domain hooks will automatically associate the creator as the first member with the owner role.
• On all subsequent nested actions (/organizations/:orgId/...): Protect them with Match Organization Role.

---

Pattern 3: Enterprise Hybrid (Super Admin Override + Tenant Manager)

In EnterpriseRBAC, combine global user roles with tenant-level organization roles in separate scenarios:

Dashboard.delete Scenarios:
├── Scenario 1 (Platform Super Admin):
│   └── Match User Role: ['super_admin']              <- Global staff override across all tenants
└── Scenario 2 (Tenant Administrator):
    └── Match Organization Role: ['admin', 'owner']   <- Local tenant manager

---

6. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match Organization Role	401 Unauthorized
Valid Member with Allowed Role	User is an active member with permitted role	200 OK / 201 Created
Valid Member with Insufficient Role	User is a member, but role is not in roles list (e.g. viewer trying to delete)	403 Forbidden
Not a Member of Organization	User is logged in, but does not belong to :orgId	403 Forbidden
Invalid Organization ID	Organization :orgId does not exist in database	404 Not Found

---

Next Steps

• Match Project Role: Granular role checks within project teams.
• Match User Role: Global user role checks for single-tenant or enterprise platforms.
• Organization Members Semantic: Complete data modeling guide for tenant memberships.