Match Email Domain

The Match Email Domain (matchEmailDomain) access rule acts as a corporate identity gate. It restricts operations based on the domain suffix of the authenticated user’s email address (e.g., @acme.com or *.acme.com).

This rule is ideal for internal company APIs, partner portals, and enterprise SaaS features that should be accessible only to employees or designated partner organizations.

---

1. How It Works

• Semantic Email Detection: The engine automatically locates the field tagged with the Email semantic module in your session configuration.
• Domain Parsing & Normalization: Splits the authenticated user’s email address at @, normalizes the domain to lowercase, and compares it against your configured domain patterns.
• Email Verification Enforcement: By default, verifies that the user’s email address has been confirmed before granting access.
• Zero Database Overhead: Evaluates purely in-memory during the PRE_FETCH phase before any database queries execute.

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

---

2. Prerequisites in the Data Domain & Session Configuration

To use Match Email Domain, your model must meet the following requirements:

1. Email Semantic Module: An email property on your User entity must be tagged with the Email semantic module.
2. Session Definition Properties: In the API Modeler’s Session Configuration tab, the email property must be included in Session Definition Properties.
3. Verification Compatibility: If requireVerified is set to true (the default), the Email semantic configuration in your Data Domain must not have requireVerification: false.

---

3. Configuration Options & Wildcard Patterns

When configuring Match Email Domain, you define:

1. Allowed Domains (domains)

A list of domain strings or wildcard patterns. An authenticated user matches if their email domain matches at least one entry in the list (case-insensitive).

Domain Pattern	Matches	Does NOT Match
acme.com	alice@acme.com ALICE@ACME.COM	alice@sub.acme.com alice@other.com
*.acme.com	alice@acme.com bob@eng.acme.com carol@dev.eng.acme.com	alice@notacme.com alice@acme.org

Wildcard Matching Rule

The *. prefix matches both the apex domain (acme.com) and any subdomain (sub.acme.com). Trailing wildcards (e.g. acme.*) are not supported.

2. Require Verified Email (requireVerified)

• true (Default): Requires that the user’s email address is marked as verified. Unverified accounts are denied access.
• false: Permits access even if the user has not yet completed email verification.

---

4. Recommended Modeling Patterns

Pattern 1: Private Internal Corporate API

To secure an entire internal backend for employee-only access, attach Match Email Domain at the global API Model level:

graph LR
    subgraph "Global API Model Scenario"
        Auth["Allow Authenticated"] --> Domain["Match Email Domain: *.corp.example.com"]
    end

---

Pattern 2: Partner Portal Partitioning

Expose partner-specific endpoints (such as beta integrations or partner webhooks) only to verified partner domains:

• On PartnerIntegration Entity:
  • Scenario: [Allow Authenticated, Match Email Domain: ['partner-alpha.com', '*.partner-beta.io']]
• Any standard user with @gmail.com or @competitor.com will receive a 403 Forbidden when attempting to access partner resources.

---

Pattern 3: Internal Platform Staff Override

Combine Match Email Domain with standard tenant access in separate scenarios to allow internal platform engineers to view system metrics across customer tenants:

InternalMetric.list Scenarios:
├── Scenario 1 (Internal Platform Staff):
│   └── Match Email Domain: ['platform.dev']         <- Internal engineers can view all telemetry
└── Scenario 2 (Tenant Customer Admin):
    └── Match Organization Role: ['admin', 'owner']   <- Customer admins can only view their own org

---

5. HTTP Status Codes Summary

Caller State	Endpoint Configuration	Resulting HTTP Status
Anonymous (No token)	Endpoint requires Match Email Domain	401 Unauthorized
Allowed Domain + Verified	Email matches domains pattern and is verified	200 OK / 201 Created
Unverified Email	Email matches domain, but user has not verified their email (requireVerified: true)	403 Forbidden
Unrecognized Domain	Email domain is not present in domains list	403 Forbidden
Missing Email in Session	Email semantic was not included in Session Definition Properties	500 Internal Server Error

---

Next Steps

• Match User Property: Generic attribute matching for departments, regions, or tiers.
• Email Semantic Module: Data modeling reference for email validation and verification.
• Session Configuration Guide: How to configure session definition properties in the API Modeler.