Multi-Tenancy

Overview

Company business data is isolated at company or organization level, as described below. IAM also supports clients under an organization. Each selected company or client has an iam_scopes row, used as Spatie’s team ID. Authentication and profile switching can run before a scope has been selected. Clients do not automatically gain access to company business packages. Their guards are client-api and client-agent, with an explicit permission catalog. IAM roles and permission pivots use scope_id; company business tables keep company_id. Profiles and assignments have exactly one company or client owner. See IAM overview for the shared access model.

Hierarchy

Organization (top-level group)
└── Company (main business entity)
    ├── Company (branch 1)
    ├── Company (branch 2)
    └── Company (branch N)

An Organization groups multiple companies under one umbrella (e.g., a holding company)
A Company is the core business unit. It can be a main company (parent) or a branch (child)
Some data (like the product catalog and assets) is shared at the organization level — all companies in the same organization see the same products
Other data (like orders, customers, stock) is scoped to the company level — each branch has its own

How tenancy is enforced

1. JWT Token carries the context

After a company human selects a profile, the JWT token encodes:

{
  "user_id": "39WSvfI8S2vEoskrylkacnLVyXd",
  "current_user_profile_id": "39WSvido6B5eCsC9CBseW3qD9Jj",
  "company_id": "39WSvi21oTnZN8i028Y80FTNT1x",
  "profile_id": "39WSvl3qi2Yx4CxcJwc2Va0e5Fp",
  "organization_id": "39WSvdttbvQAo0MjVqqFBHQiJhz",
  "type": "user"
}

Every request automatically carries this context.

2. Middleware resolves the tenant

The exowpee.teams middleware (registered by the IAM package) runs on every protected route and:

Reads the JWT token
Resolves the selected company_id or client_id and organization_id
Sets the tenant context for the request
Configures Spatie’s permission team system using the matching IAM scope

The parent does not replace authentication, active-session checks or business authorization. Protected routes also need a complete access group, such as exowpee.company or exowpee.client.

3. Queries are automatically scoped

Models use the resolved tenant context to scope queries:

// In a controller — data is automatically filtered by company
$orders = Order::where('company_id', company()->id)->paginate();

// Using the company() helper
$customers = Customer::where('company_id', company()->id)->get();

4. Policies check ownership

Authorization policies verify that the requested resource belongs to the user’s current organization/company:

class ProductPolicy
{
    public function view($user, Product $product): bool
    {
        return auth()->profile()?->hasPermissionTo('products.retrieve')
            && $product->organization_id === getTeamOrganization()->id;
    }
}

Data scoping by level

Level	Scoped Data	Shared Across
Organization	Products, categories, variants, vendors, assets	All companies in the organization
Company	Orders, customers, stock levels, ledger entries, members	Only within that company
User	Authentication, user profiles	Global

For businesses with multiple branches, the product catalog should be the same everywhere. A “Samsung Galaxy A54” in the Cotonou branch is the same product in the Porto-Novo branch. But each branch manages its own stock levels, orders, and customers independently.

Switching companies

A user can belong to multiple companies through different UserProfiles. To switch context:

curl -X POST http://localhost:8000/v1/auth/switch-user-profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_profile_id": "TARGET_PROFILE_ID"}'

This returns a new JWT token with the updated company_id and organization_id.

Helper functions

Exowpee provides global helpers to access the current tenant context anywhere in the code:

// Get the current company model
company();

// Get the current user profile
userProfile();

// Get the current user
user();

// Get the current organization
getTeamOrganization();

// Check permission in current context
userHasPermissionTo('products.create');

These helpers are defined in packages/shared/src/Helpers/helpers.php and app/Helpers/helpers.php.

For developers

When writing new code:

Always scope queries by company_id or organization_id
Always check ownership in policies
Never assume a single company — the system is multi-tenant
Use the company() and getTeamOrganization() helpers instead of hardcoding IDs
Write migrations with company_id or organization_id columns on any tenant-specific table

Getting started

Architecture

Developer guide

Operations

More

Multi-Tenancy

Overview

Hierarchy

How tenancy is enforced

1. JWT Token carries the context

2. Middleware resolves the tenant

3. Queries are automatically scoped

4. Policies check ownership

Data scoping by level

Switching companies

Helper functions

For developers

​Overview

​Hierarchy

​How tenancy is enforced

​1. JWT Token carries the context

​2. Middleware resolves the tenant

​3. Queries are automatically scoped

​4. Policies check ownership

​Data scoping by level

​Why organization-level sharing?

​Switching companies

​Helper functions

​For developers

Overview

Hierarchy

How tenancy is enforced

1. JWT Token carries the context

2. Middleware resolves the tenant

3. Queries are automatically scoped

4. Policies check ownership

Data scoping by level

Why organization-level sharing?

Switching companies

Helper functions

For developers