Multi-tenancy

Multi-tenancy is one of the hardest problems in SaaS development. You need to isolate data so Company A never sees Company B’s, handle authentication across organizational boundaries, manage two levels of admin, scope every query to the current tenant, and prevent cross-tenant access even from buggy or malicious code. Most teams spend weeks building this. Feather provides it out of the box — choose multi-tenant when you run feather new.

How it works

Feather uses domain-based tenant isolation. When a user signs in with bob@acme.com:

Extract the domain

Feather reads acme.com from the email.

Match a tenant

It looks up the tenant registered to that domain.

Assign the user

The user is attached to that tenant.

Scope every query

All subsequent queries are scoped to it.

Public email domains

By default Gmail, Outlook, Yahoo and other consumer providers are blocked — users must sign in with their work email. For B2B and B2C apps that support both:

.env

FEATHER_ALLOW_PUBLIC_EMAILS=true

Users with public emails are then created with tenant_id=None. Use the post-login callback to handle account and tenant creation for them.

The two-axis authority model

Feather separates tenant authority — what you can do within your organization — from platform authority, cross-organization operator power.

Axis	Field	Scope	Example
Tenant role	`user.role`	Within one tenant	”admin”, “editor”, “user”
Platform authority	`user.is_platform_admin`	Across all tenants	True/False

Tenant admins do not bypass tenant isolation. An admin at Acme Corp cannot access data from Beta Inc. That requires explicit platform admin privileges.

Tenant admin

Approves and suspends users in their tenant, changes roles within it, views error logs scoped to it. Cannot see other tenants or their data.

Platform admin

Creates tenants and assigns domains, approves and suspends tenants, views all users and platform-wide analytics. Granted only via CLI, never the web UI.

Granting platform admin

feather platform-admin admin@example.com            # grant
feather platform-admin admin@example.com --revoke   # revoke

Admin pages in multi-tenant mode

Page	Route	Who can access
Users	`/admin/users`	Tenant admin — users in the current tenant
User detail	`/admin/users/<id>`	Tenant admin — approve, suspend, change roles
Error logs	`/admin/logs`	Tenant admin — errors scoped to the tenant
Tenants	`/admin/tenants`	Platform admin only — all tenants, create new
Tenant detail	`/admin/tenants/<id>`	Platform admin only — info, users, approve, suspend

Data isolation, enforced at three layers

Route layer
Service layer
Model layer

get_current_tenant_id() returns the authenticated user’s tenant.

from feather import get_current_tenant_id

@api.get('/projects')
@auth_required
def list_projects():
    tenant_id = get_current_tenant_id()
    return Project.query.filter_by(tenant_id=tenant_id).all()

require_same_tenant() guards against cross-tenant access.

from feather.auth import require_same_tenant

def get_project_or_404(project_id):
    project = Project.query.get_or_404(project_id)
    require_same_tenant(project.tenant_id)  # raises 403 on mismatch
    return project

TenantScopedMixin adds tenant_id and scoped queries.

from feather.db.mixins import TenantScopedMixin

class Project(UUIDMixin, TenantScopedMixin, Model):
    __tablename__ = 'projects'
    name = db.Column(db.String(100))

projects = Project.for_tenant(tenant_id).all()

require_same_tenant() is a hard stop — even tenant admins cannot bypass it. Cross-tenant operations require platform admin routes with explicit @platform_admin_required decorators.

feather check reports a query on a tenant-scoped model with no tenant filter as the tenant-isolation error, so a missed filter fails CI rather than leaking data.

The Tenant model

The scaffolded model supports both B2B (domain-based) and B2C (individual) patterns.

class Tenant(Model):
    slug = db.Column(db.String(64), unique=True, nullable=False)
    domain = db.Column(db.String(255), nullable=True)   # nullable for B2C
    name = db.Column(db.String(255), nullable=False)
    type = db.Column(db.String(50), nullable=True)      # "company", "individual", etc.
    status = db.Column(db.String(20), default="pending")

B2B tenants — set domain to auto-assign users by email
B2C tenants — leave domain as None and create individually via the post-login callback
type — classify tenants for billing, features or reporting

Tenant lifecycle

Platform admin creates the tenant

Via /admin/tenants. Sets name, slug and optionally an email domain, creates the initial tenant admin (auto-approved). The tenant starts pending.

Platform admin approves the tenant

The tenant becomes active.

Users sign up with a matching email domain

They are auto-assigned to the tenant and created in a suspended state.

Tenant admin approves the users

Via /admin/users.

This flow gives you both a platform-level and a tenant-level approval gate.

Get started

Building the UI

Backend

Features

Tooling

Testing

Deployment

How it works

Public email domains

The two-axis authority model

Tenant admin

Platform admin

Admin pages in multi-tenant mode

Data isolation, enforced at three layers

The Tenant model

Tenant lifecycle

​How it works

​Public email domains

​The two-axis authority model

Tenant admin

Platform admin

​Admin pages in multi-tenant mode

​Data isolation, enforced at three layers

​The Tenant model

​Tenant lifecycle

How it works

Public email domains

The two-axis authority model

Admin pages in multi-tenant mode

Data isolation, enforced at three layers

The Tenant model

Tenant lifecycle