Tenant and context
Keep App reads, writes, and background work inside the correct tenant and authorized organization scope.
Tenant and context
What your App must do
Tenant context establishes which customer's data your code may reach. Core restores it before protected tenant HTTP handlers run. Your App then applies its operation permissions, record visibility, and business rules inside that tenant. A selected organization or workspace does not grant access.
| Your code path | Required action |
|---|---|
| Generated Resource API | Keep the generated tenant and installation middleware, query scope, and Policy |
| New record | Derive owner attributes through the Resource authorization contract |
| Organization-filtered list | Use the page's declared scope and backend authorization together |
| Background work | Restore trusted tenant context and the actor authority the operation requires |
| Event consumer | Verify the envelope belongs to the already restored tenant; never switch to accept a mismatch |
Use Add a protected API for HTTP implementation and Handle events and jobs for background execution.
Tenant, owner, and page scope
| Concept | Responsibility |
|---|---|
| Tenant | Customer isolation across data, files, permissions, and execution |
| Record owner | Durable ownership declared by the Resource, such as tenant or Legal Entity |
| Legal Entity / Operating Unit | Organizational targets within one tenant |
| Access Grant | Authority for an actor, action, scope, and subject population |
| Workspace or page selection | User interface context or a narrower requested result set |
Membership can make an organization selectable; it does not authorize its
records. A page-owned organization selector belongs in the Route Surface's
organizationScope slot. Standard lists use useOrganizationListScope with the
read permission. Custom relations and multiple-permission pages keep an explicit
adapter. Common-data profiles have no selector by default. Detail and edit pages
display the stored owner. See Build an App screen.
Use the authorization contract
These methods are defined by
Nexia\Laravel\Access\Contracts\ResourceAuthorization in the SDK. Use them in the
query, Policy, and creation path rather than independently reconstructing scope.
| Method | Purpose |
|---|---|
scopeVisible($query, $resourceKey, $legalEntityId) | Restrict a list to authorized rows |
scopeVisibleForLegalEntities($query, $resourceKey, $legalEntityIds) | Standard direct-owner multi-Legal-Entity lists |
recordMatches($record, $resourceKey, $legalEntityId) | Check whether the stored record matches the authorized boundary |
creationAttributes($resourceKey, $legalEntityId) | Derive owner columns for creation |
The singular Legal Entity argument is optional. Do not supply an unchecked browser value as an internal ID. The multi-target method does not implement custom relationship or Operating Unit visibility. Those belong to the Resource's explicit query and policy. Permissions and roles explains the other inputs to the decision.
Restore background context explicitly
At a trusted dispatch boundary, the host contract
Nexia\Tenancy\Contracts\TenantRunner offers these entry points:
public function runFor(int|string $tenantKey, callable $callback): bool;
public function runForAll(callable $callback): int;These are interface signatures, not job implementations. runFor() returns
false if the tenant no longer exists; runForAll() returns the number presented
to the callback. Both restore and clear tenant context. Neither restores an actor.
Missing or ambiguous context must stop work, never select a default tenant.
An Inbox consumer already running within its tenant must reject an envelope for another tenant. If the operation depends on a user's authority, the supported delegated path restores and reauthorizes that actor at execution time. A system consumer has no implicit user privileges.
Diagnose a scope problem
Start with the tenant domain, then App installation, permission/grant, requested organization targets, and stored record owner. Do not widen a query to make a missing record appear. Fix tenant context problems provides symptom-specific checks.