🐚 ShellApps Blog
← Back to posts

Multi-Tenant Auth Done Right

· Sarah Chen

If you're building a B2B product, you'll need multi-tenancy eventually. Getting auth right from the start saves months of painful migration later.

What Multi-Tenancy Means for Auth

In a multi-tenant system, one user might belong to multiple organisations. Each organisation has its own settings, roles, and data isolation requirements. Your auth layer needs to handle all of this without leaking data between tenants.

ShellApps Identity supports multi-tenancy natively. Here's how we approach it.

Tenant Isolation

Every tenant (we call them "apps" in ShellApps) gets isolated:

  • User pools — Users are scoped to an app. The same email can register in multiple apps without conflict.
  • Configuration — Each app has its own password policy, 2FA requirements, session duration, and branding.
  • Data — User records, sessions, and audit logs are partitioned by app ID. There's no way to accidentally query across tenants.

Roles and Permissions

ShellApps Identity ships with a flexible role system:

  • Built-in roles — owner, admin, member, viewer cover most use cases
  • Custom roles — Define your own with granular permissions
  • Role inheritance — An admin automatically inherits all member permissions

Roles are checked at the API level:

// Middleware example
const user = await verifyToken(req.headers.authorization);
if (!user.hasRole('admin')) {
  return res.status(403).json({ error: 'Insufficient permissions' });
}

Session Management

Each tenant can configure its own session rules:

  • Token lifetime — From 15 minutes for high-security apps to 30 days for consumer apps
  • Concurrent sessions — Allow multiple devices or restrict to one active session
  • IP restrictions — Lock sessions to specific IP ranges for corporate environments

When a user switches between organisations, they get a new scoped token without re-authenticating. The experience is seamless from the user's perspective.

Audit Logging

Every auth event is logged per tenant:

  • Login attempts (successful and failed)
  • Password changes
  • 2FA enrollment and method changes
  • Role assignments
  • Token refreshes and revocations

Audit logs are queryable via API and visible in the admin dashboard. Set retention periods per tenant — some industries require years of records.

Migration Path

Already have users in your own database? We support bulk import via CSV or API. Password hashes from bcrypt, argon2, and PBKDF2 are supported natively — users won't need to reset their passwords.

Getting Started

Multi-tenancy is available on all ShellApps Identity plans. The free tier supports up to 3 apps with 1,000 users each — enough to build and validate your product before scaling.

Check the auth documentation for the full multi-tenancy guide, or reach out if you have questions about your specific architecture.

auth architecture multi-tenancy