Multi-tenancy

Multi-tenancy is among the harder problems in SaaS. You have to isolate data so one customer never sees another’s, handle authentication across organizational boundaries, manage two levels of admin, scope every query to the current tenant, and keep buggy code from crossing those lines. Feather provides all of it. Choose multi-tenant when you run feather new.

How it works

Tenants are identified by email domain. When a user signs in as 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 later queries are scoped to it.

Public email domains

Gmail, Outlook, Yahoo and other consumer providers are blocked by default, so users sign in with a work address. For apps serving both businesses and individuals:

.env

FEATHER_ALLOW_PUBLIC_EMAILS=true

Users with public addresses are then created with tenant_id=None. Use the post-login callback to create their account and tenant.

The two-axis authority model

Feather separates tenant authority, what you can do inside your organization, from platform authority, operator power across organizations.

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

Tenant admins do not bypass tenant isolation. An admin at Acme Corp cannot reach data belonging to Beta Inc. That requires platform admin rights.

Tenant admin

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

Platform admin

Creates tenants and assigns domains, approves and suspends them, and views all users and platform-wide analytics. Granted only through the 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 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 that tenant admins cannot bypass. Cross-tenant operations belong on platform admin routes with an explicit @platform_admin_required decorator.

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

The Tenant model

The scaffolded model covers both domain-based and individual tenants.

class Tenant(Model):
    slug = db.Column(db.String(64), unique=True, nullable=False)
    domain = db.Column(db.String(255), nullable=True)   # nullable for individuals
    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")

Business tenants. Set domain to assign users by email automatically.
Individual tenants. Leave domain as None and create them in the post-login callback.
type. Classify tenants for billing, features or reporting.

Tenant lifecycle

Platform admin creates the tenant

Through /admin/tenants. Sets name, slug and optionally an email domain, and creates the first tenant admin, auto-approved. The tenant starts pending.

Platform admin approves the tenant

It becomes active.

Users sign up with a matching email domain

They are assigned to the tenant and created suspended.

Tenant admin approves the users

Through /admin/users.

The result is an approval gate at both the platform and the tenant level.

Get started

Tutorial: build a Kanban app

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 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 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 at three layers

The Tenant model

Tenant lifecycle