DEV Community: Oladele David

How to Model Teams Inside a Multi-Tenant Product

Oladele David — Tue, 02 Jun 2026 01:03:00 +0000

Once you have the tenant boundary, the next question is what lives inside it. This is how I modeled teams with roles, invitations, and lifecycle states that match real organizational behavior.

This is Part 2 of the series Building Multi-Tenant Systems That Match the Real World.
Part 1: Designing Multi-Tenant Backends With Both Ownership and Team Access

The Gap Between "List of Users" and a Real Team
The Team Member Is Not the Same as the User
Membership Has a Lifecycle
Roles Give Membership Meaning
Predefined Roles vs Custom Permission Sets
The Invitation Flow Is Part of the Data Model
How Permission Resolution Actually Works
What the API Surface Looks Like
What I Would Avoid
Closing Thought
Suggested Diagrams

The Gap Between "List of Users" and a Real Team

In Part 1, I covered why tenants should be modeled as organizations with boundaries, not just data buckets with a tenantId column.

Once you have that boundary in place, a new question shows up immediately:

Who is inside the organization, and what are they allowed to do?

The naive answer is "just store user IDs and give them a role."

That answer falls apart quickly because a real team inside an organization is not just a list of users.

It is a set of relationships with state:

Some people have been invited but not yet accepted
Some have accepted and are active
Some have been suspended temporarily
Some have been removed but their records still matter for audit purposes
Different people have different operating responsibilities
The same person may have different responsibilities in a different organization they belong to

Once you recognize that, "store user IDs with a role" becomes an inadequate model.

Here is what a real team model needs to do instead.

The Team Member Is Not the Same as the User

This is the first thing I had to internalize.

A User is an identity in the system.

A TeamMember (or StoreStaff, WorkspaceMember, ClinicStaff — whatever your domain calls it) is a relationship between a user and an organization.

Those are two different things, and mixing them up causes problems.

When you mix them up, you end up with schemas like this:

interface User {
  id: string;
  email: string;
  organizationId: string;   // ← implicit membership
  role: string;             // ← implicit, unscoped role
}

That design has four problems:

A user can only belong to one organization.
Role is global, not scoped to the organization.
There is no lifecycle for the membership itself.
Removing someone from an organization means deleting or modifying the user record.

The cleaner design is to keep the user identity separate and make membership an explicit entity:

interface User {
  id: string;
  email: string;
}

interface TeamMember {
  id: string;
  userId: string;
  organizationId: string;
  roleId: string;
  invitedBy: string;
  invitedAt: Date;
  acceptedAt?: Date;
  status: MembershipStatus;
}

Now membership has its own shape, its own state, its own audit fields, and its own lifecycle.

The user can belong to multiple organizations by having multiple TeamMember records.

Removing someone from an organization means changing the status of their TeamMember record, not touching their user identity.

Membership Has a Lifecycle

Most membership models in tutorials are binary: you are either in the organization or you are not.

Real systems need at least four states:

enum MembershipStatus {
  PENDING   = 'pending',    // invited but not yet accepted
  ACTIVE    = 'active',     // accepted and currently active
  SUSPENDED = 'suspended',  // temporarily blocked
  REMOVED   = 'removed',    // no longer a member
}

Here is why each state matters.

PENDING

When you invite someone, you should not grant them access immediately.

A pending member has been invited but has not yet confirmed they want to be part of this organization.

During this state, the membership record exists but should carry no operating permissions.

ACTIVE

Once the invitation is accepted, the member becomes active.

Active is the only state where the user should have the permissions their role grants.

SUSPENDED

Sometimes you need to temporarily block a team member without removing them entirely.

A suspended member loses all effective permissions but their record stays intact.

This is useful for dispute resolution, compliance situations, or temporary leaves.

REMOVED

A removed member is no longer a participant in the organization.

But their record should still exist for audit purposes.

You want to know that a particular action was taken while this person was an active member, even after they have been removed.

The lifecycle looks like this:

                       accept
PENDING  ─────────────────────────────► ACTIVE ──► SUSPENDED
   │                                                    │
   │  reject / cancel                                   │ reactivate
   │                                                    ▼
   └───► (record deleted)                            ACTIVE
                                              │
                                              │ remove
                                              ▼
                                           REMOVED

Keeping this lifecycle in the schema rather than just deleting records makes your system much easier to audit and debug.

Roles Give Membership Meaning

A team member with a status is not enough. You also need to know what they are allowed to do.

That is what roles are for.

A role is not just a label. It is a named bundle of permissions scoped to a domain.

interface Role {
  id: string;
  name: string;
  slug: string;
  description?: string;
  scope: 'platform' | 'organization';
  isSystem: boolean;
}

interface Permission {
  id: string;
  name: string;       // e.g. 'products.create'
  resource: string;   // e.g. 'products'
  action: string;     // e.g. 'create'
  scope: 'platform' | 'organization';
}

interface RolePermission {
  roleId: string;
  permissionId: string;
}

A few details worth noting:

scope separates platform-wide roles from organization-specific roles. A platform admin role and an organization manager role are fundamentally different things.
isSystem marks built-in roles that should not be deleted. You can update their permissions, but you cannot remove them.
slug gives you a stable identifier you can reference in code without coupling to database IDs.

With this structure, assigning a role to a team member is just setting the roleId on the TeamMember record.

Predefined Roles vs Custom Permission Sets

For most organizations, a fixed set of predefined roles covers 90% of the cases:

const PREDEFINED_ROLES = [
  {
    slug: 'org_manager',
    name: 'Organization Manager',
    description: 'Full operational access except owner-only actions',
    permissions: [
      'products.*',
      'orders.*',
      'customers.*',
      'team.manage_staff',
      'analytics.view',
      'settings.view',
    ],
  },
  {
    slug: 'order_processor',
    name: 'Order Processor',
    description: 'Handles order operations only',
    permissions: [
      'orders.view',
      'orders.process',
      'orders.update_status',
      'customers.view',
    ],
  },
  {
    slug: 'content_editor',
    name: 'Content Editor',
    description: 'Manages product content and media',
    permissions: [
      'products.view',
      'products.edit',
      'media.*',
      'categories.manage',
    ],
  },
  {
    slug: 'financial_viewer',
    name: 'Financial Viewer',
    description: 'Read-only access to financial data',
    permissions: [
      'financials.view',
      'analytics.view',
      'orders.view',
    ],
  },
];

These roles should cover the most common organizational shapes without requiring configuration.

For edge cases where a specific member needs permissions that do not map cleanly to a standard role, I keep a customPermissions field on the team member record:

interface TeamMember {
  id: string;
  userId: string;
  organizationId: string;
  roleId: string;
  status: MembershipStatus;
  customPermissions?: string[];  // per-member overrides
  invitedBy: string;
  invitedAt: Date;
  acceptedAt?: Date;
}

Custom permissions are additive, not replacing the role.

This means you can say "this person has the order_processor role, plus analytics.view" without creating a new role just for one team member.

Two rules I enforce:

Custom permissions can only extend a role, not override it entirely.
No member can be given permissions their role scope does not allow — a store-scoped team member cannot receive platform-level permissions.

The Invitation Flow Is Part of the Data Model

One of the mistakes I see teams make is treating the invitation flow as a side feature — an email is sent, and then the user is added.

The invitation state is data, and it should live in the database.

This gives you:

a record of who invited whom and when
the ability to list and cancel pending invitations
the ability to resend invitations without sending duplicates
the ability to reject an invitation gracefully
audit history even for invitations that were never accepted

An invitation creates a TeamMember record immediately, with status PENDING.

async function inviteTeamMember(
  organizationId: string,
  invitedByUserId: string,
  email: string,
  roleSlug: string,
) {
  // find or create the user account
  let user = await db.user.findUnique({ where: { email } });

  if (!user) {
    user = await db.user.create({
      data: { email, status: 'invited' },
    });
    // send account setup email with invitation link
    await sendAccountSetupInvitation(user.email);
  }

  const role = await db.role.findUnique({ where: { slug: roleSlug } });

  // create membership in PENDING state
  const membership = await db.teamMember.create({
    data: {
      userId: user.id,
      organizationId,
      roleId: role.id,
      invitedBy: invitedByUserId,
      status: 'pending',
    },
  });

  return membership;
}

When the invitee accepts, the status moves to ACTIVE and acceptedAt is stamped:

async function acceptInvitation(organizationId: string, userId: string) {
  await db.teamMember.update({
    where: {
      userId_organizationId: { userId, organizationId },
    },
    data: {
      status: 'active',
      acceptedAt: new Date(),
    },
  });
}

When the invitee rejects, or an admin cancels the invitation, you have a choice: delete the record entirely or update the status. I prefer deletion for rejected and cancelled invitations because they carry no operating significance and create noise in audit logs.

async function cancelInvitation(organizationId: string, userId: string) {
  await db.teamMember.delete({
    where: {
      userId_organizationId: { userId, organizationId },
    },
  });
}

How Permission Resolution Actually Works

When a request comes in and you need to know what the current user is allowed to do inside an organization, there are three questions:

Are they the owner?
If not, are they an active team member?
If yes, what does their role plus any custom permissions allow?

async function resolvePermissions(
  userId: string,
  organizationId: string,
): Promise<string[]> {
  // owners get everything
  const isOwner = await isOrganizationOwner(userId, organizationId);
  if (isOwner) return ['*'];

  // inactive members get nothing
  const membership = await db.teamMember.findUnique({
    where: {
      userId_organizationId: { userId, organizationId },
    },
    include: {
      role: {
        include: { permissions: true },
      },
    },
  });

  if (!membership || membership.status !== 'active') {
    return [];
  }

  const rolePermissions = membership.role.permissions.map((p) => p.name);
  const customPermissions = membership.customPermissions ?? [];

  return [...new Set([...rolePermissions, ...customPermissions])];
}

Then checking a specific permission becomes a simple evaluation:

function hasPermission(
  grantedPermissions: string[],
  required: string,
): boolean {
  if (grantedPermissions.includes('*')) return true;
  if (grantedPermissions.includes(required)) return true;

  const [resource] = required.split('.');
  return grantedPermissions.includes(`${resource}.*`);
}

This supports three grant patterns:

Full wildcard (*): used for owners
Resource wildcard (products.*): used for roles with broad domain ownership
Specific permission (products.create): used for narrow operational roles

The resolution order is always: owner check first, active status check second, permission evaluation last.

What the API Surface Looks Like

Team management operations should be first-class routes scoped to the organization:

# List current team members
GET    /v1/organizations/:orgId/team

# Invite a new member
POST   /v1/organizations/:orgId/team

# List pending invitations
GET    /v1/organizations/:orgId/team/invites

# Resend an invitation
POST   /v1/organizations/:orgId/team/invites/:userId/resend

# Cancel an invitation
DELETE /v1/organizations/:orgId/team/invites/:userId

# Accept your own invitation (self-service)
PUT    /v1/organizations/:orgId/team/me/accept

# Reject your own invitation (self-service)
PUT    /v1/organizations/:orgId/team/me/reject

# View your own effective permissions (self-service)
GET    /v1/organizations/:orgId/team/me/permissions

# Update a member's role (admin)
PUT    /v1/organizations/:orgId/team/:userId/role

# Suspend a member (admin)
PUT    /v1/organizations/:orgId/team/:userId/suspend

# Reactivate a suspended member (admin)
PUT    /v1/organizations/:orgId/team/:userId/reactivate

# Remove a member (admin)
DELETE /v1/organizations/:orgId/team/:userId

A few structural points worth noting:

Self-service endpoints (/me/...) are separated from admin endpoints because they require different authorization logic. A member can accept or view their own permissions without needing team.manage_staff.
Suspension and removal are separate endpoints because they have different semantics, different audit implications, and different reversal paths.
The invitation list is a distinct route so it can be paginated, filtered, and canceled without mixing pending invitations into the active member list.

What I Would Avoid

1. Granting permissions the moment an invitation is sent

A PENDING member has been invited, not admitted. Treat those two events differently.

2. Deleting team member records on removal

You lose audit history. Use a REMOVED status instead.

3. Mixing `customPermissions` with role replacement

Custom permissions should extend a role. If someone needs a very different permission set, create a new role rather than stacking overrides on a single record.

4. Skipping the status check in permission resolution

The permission resolution path must always check status === 'active' before returning any permissions. A suspended member's role may still exist in the database. Status gating is the only reliable guard.

5. Encoding team structure in the user table

Adding a role column to the user record makes multi-organization behavior nearly impossible to support cleanly. Membership is a relationship, not a user attribute.

6. Letting the same role exist with different meanings in different organizations

If your predefined roles are system roles, they should mean the same thing everywhere. The organization-specific layer should be in the assignment and optional customization, not in redefining what store_manager means per store.

Closing Thought

The key shift in this article is the same one from Part 1, applied one level deeper:

A team is not a list of users. It is a set of active relationships with state, roles, and boundaries.

Once you model it that way:

invitations become first-class data instead of fire-and-forget emails
lifecycle management becomes natural instead of hacky
permission resolution becomes a straightforward function instead of scattered conditional logic
multi-organization membership becomes a non-event instead of a schema crisis

The patterns here — separate the membership from the identity, give membership a lifecycle, resolve permissions from status and role together — apply well beyond marketplace systems.

Any B2B SaaS tool, internal operations platform, healthcare system, or agency tool that has "workspaces with multiple people" needs to make these same decisions eventually.

Modeling them deliberately at the start is much cheaper than untangling them later.

In Part 3, I will cover how to separate platform-level authority from organization-level authority — the point where "admin" starts to mean different things depending on who is asking.

Designing Multi-Tenant Backends With Both Ownership and Team Access

Oladele David — Fri, 17 Apr 2026 18:38:12 +0000

A practical architecture pattern for systems where one user can own, join, and operate multiple organizations.

The Problem With Most Multi-Tenant Tutorials
The Shift: Model Organizations, Not Just Data Buckets
The Core Model
Why Ownership and Team Access Should Be Separate
Support One User Across Many Organizations
Make Organization Context Explicit Per Request
Scope Permissions to the Organization
Treat Team Management as Part of the Core Architecture
What This Model Buys You
What I Would Avoid
Closing Thought
Suggested Diagrams

The Problem With Most Multi-Tenant Tutorials

// The shape that changed how I think about multi-tenancy
User
  -> OrganizationOwner[]
  -> TeamMembership[]

Organization
  -> owners
  -> team members
  -> roles
  -> permissions

Most multi-tenant backend examples stop too early.

They show a tenantId column, maybe a middleware that reads it from the request, and call it multi-tenancy.

That is enough for data partitioning. It is not enough for real products.

Real systems usually need all of this:

One user can own more than one organization
One user can also work inside organizations they do not own
Each organization can have internal roles
Permissions are scoped to one organization, not the whole platform
Some actions belong to owners only
Some actions belong to staff with the right role
The same person can be an owner in one organization and a staff member in another

Once those rules show up, a plain tenantId model starts to crack.

The better mental model is this: model tenancy around ownership, membership, and scoped permissions, not just row filtering.

The Shift: Model Organizations, Not Just Data Buckets

A lot of systems start with something like this:

model Project {
  id       String @id
  tenantId String
  name     String
}

model User {
  id    String @id
  email String @unique
}

Then every query becomes:

await db.project.findMany({
  where: { tenantId: currentTenantId },
});

That part is fine.

The problem is what happens next.

Who is allowed to access that tenant?

Is the current user the owner?
Are they part of the tenant team?
Can they manage billing?
Can they invite staff?
Can they edit content but not touch payouts?
Can they belong to three tenants at the same time?

Those are not edge cases. They are normal cases in SaaS, marketplaces, agencies, clinics, schools, franchise systems, and internal business software.

So the real unit is not just tenant data.

The real unit is an organization with internal people, roles, and operating boundaries.

The Core Model

I like to separate three ideas:

User
One person with one identity in the system.
Organization
The tenant boundary. This could be a store, workspace, clinic, school, client account, or business unit.
Membership
The relationship between a user and an organization.

Then I split membership into two business concepts:

Owner relationship
Team relationship

That distinction matters because ownership usually carries special meaning that normal staff membership should not inherit automatically.

A simplified model looks like this:

type MembershipStatus = 'pending' | 'active' | 'suspended' | 'removed';

interface User {
  id: string;
  email: string;
}

interface Organization {
  id: string;
  name: string;
}

interface OrganizationOwner {
  userId: string;
  organizationId: string;
  role: 'owner';
}

interface TeamMember {
  userId: string;
  organizationId: string;
  roleId: string;
  status: MembershipStatus;
}

This gives you room for the rules most systems actually need:

ownership is explicit
staff membership is explicit
membership lifecycle is explicit
role assignment is explicit

That is much easier to reason about than stuffing everything into one users.organizationId column.

Why Ownership and Team Access Should Be Separate

I used to think owner was just another role.

I do not think that anymore.

Owners are different because they usually have platform-level significance:

they created the organization
they are the fallback authority
they can perform destructive admin actions
they may control billing or legal settings
they often bypass normal role restrictions

That makes ownership closer to a structural relationship than a normal permission bundle.

So instead of modeling the owner exactly like every other staff role, I prefer to keep a direct ownership link and then layer team roles on top.

A simplified ownership check can look like this:

async function isOrganizationOwner(userId: string, organizationId: string) {
  const membership = await db.organizationOwner.findUnique({
    where: {
      userId_organizationId: { userId, organizationId },
    },
  });

  return membership?.role === 'owner';
}

Then team permissions stay independent:

async function getTeamPermissions(userId: string, organizationId: string) {
  const membership = await db.teamMember.findUnique({
    where: {
      userId_organizationId: { userId, organizationId },
    },
    include: {
      role: {
        include: {
          permissions: true,
        },
      },
    },
  });

  if (!membership || membership.status !== 'active') {
    return [];
  }

  return membership.role.permissions.map((p) => p.name);
}

That split makes later decisions cleaner:

owner logic stays simple
staff logic stays flexible
permission resolution stays organization-scoped
invitation and suspension flows stay easy to model

Support One User Across Many Organizations

This is where weak multi-tenant designs usually break.

If your first schema assumes one user belongs to one tenant, you will eventually have to undo it.

In practice, users often need to do all of these:

create one organization
join another organization as staff
leave one organization
manage several organizations from one login
switch active context per request

That means the relationship is many-to-many.

Not this:

interface User {
  id: string;
  organizationId: string;
}

But this:

interface User {
  id: string;
}

interface OrganizationMembership {
  userId: string;
  organizationId: string;
  type: 'owner' | 'staff';
}

Once you accept that model, the request lifecycle gets cleaner too.

Instead of assuming "the user has one tenant," you ask:

which organization is this request acting on?
does this user have access to that organization?
what kind of access do they have inside it?

That is a much better fit for real systems.

Make Organization Context Explicit Per Request

If a user can operate multiple organizations, the backend needs an explicit organization context per request.

That context can come from:

a route param
a header
a subdomain
a session value
a token claim plus explicit switching

I like explicit request-level context because it keeps authorization honest.

A small extraction helper looks like this:

function extractOrganizationId(request: any): string | undefined {
  return (
    request.params.organizationId ||
    request.headers['x-organization-id'] ||
    request.body?.organizationId
  );
}

Then every protected handler resolves access against that organization, not against some vague "current account" idea.

For example:

async function assertOrganizationAccess(userId: string, organizationId: string) {
  const isOwner = await isOrganizationOwner(userId, organizationId);
  if (isOwner) return true;

  const membership = await db.teamMember.findUnique({
    where: {
      userId_organizationId: { userId, organizationId },
    },
  });

  if (!membership || membership.status !== 'active') {
    throw new ForbiddenError('You do not have access to this organization');
  }

  return true;
}

This pattern generalizes well across systems:

seller platforms with stores
agency platforms with client workspaces
healthcare systems with clinics
education systems with campuses
internal tools with business units

The names change. The access model does not.

Scope Permissions to the Organization

Once a user can belong to multiple organizations, global roles stop being enough.

admin is too vague.

Admin of what?

The platform?
One organization?
Billing?
Orders?
Content?
Reporting?

I prefer permission names that describe both the resource and the action:

type Permission =
  | 'products.view'
  | 'products.create'
  | 'products.edit'
  | 'orders.view'
  | 'orders.process'
  | 'team.manage'
  | 'billing.view';

Then evaluate them inside one organization boundary:

async function userHasPermissions(
  userId: string,
  organizationId: string,
  required: string[],
) {
  const isOwner = await isOrganizationOwner(userId, organizationId);
  if (isOwner) return true;

  const permissions = await getTeamPermissions(userId, organizationId);

  return required.every((permission) => {
    if (permissions.includes(permission)) return true;

    const [resource] = permission.split('.');
    return permissions.includes(`${resource}.*`);
  });
}

A few details make this model practical:

permission checks are organization-scoped
owners can bypass normal staff restrictions
wildcard permissions are supported for operational roles
team members can be pending, active, suspended, or removed
the same user can have different permission sets in different organizations

That last point is the important one.

A user is not just "an admin."

A user is "an admin in organization A, but a viewer in organization B."

That is the level where multi-tenant authorization starts to become useful.

Treat Team Management as Part of the Core Architecture

If your product supports organization-based work, team operations should be first-class backend flows.

That means treating these as core resources:

invitations
team members
roles
membership status
permission discovery

A small REST shape might look like this:

GET    /v1/organizations/:organizationId/team
POST   /v1/organizations/:organizationId/team
GET    /v1/organizations/:organizationId/team/invites
POST   /v1/organizations/:organizationId/team/invites/:userId/resend
PUT    /v1/organizations/:organizationId/team/me/accept
GET    /v1/organizations/:organizationId/team/me/permissions
PUT    /v1/organizations/:organizationId/team/:userId/role

That API shape tells you something important about the architecture:

team members belong to an organization
invitations belong to an organization
permission checks happen inside an organization
self-service actions like accept or reject are different from admin actions

This is the point where multi-tenancy stops being just database design and becomes product architecture.

What This Model Buys You

The biggest benefit is not elegance. It is fewer rewrites later.

This model gives you a path for:

multiple organizations per user
clear owner semantics
organization-specific teams
invitation flows
scoped permissions
lifecycle states for team members
safer access checks
cleaner auditing

It also helps your codebase stay honest.

Instead of hiding access logic in random service methods, you can center everything around one question:

What can this user do inside this organization right now?

That question stays useful across many kinds of systems.

What I Would Avoid

1. One user, one tenant

It feels simpler until the first operator, consultant, or agency user needs access to two organizations.

2. Treating owner as just another role

It can work, but ownership usually carries different platform semantics and deserves explicit modeling.

3. Global roles for tenant behavior

A single global admin or manager role quickly becomes ambiguous in multi-organization systems.

4. Implicit tenant resolution everywhere

If a request can affect organization-scoped data, the organization context should be explicit and verifiable.

5. Mixing access checks with unrelated business logic

Authorization becomes easier to reason about when ownership, membership, and permission resolution are centralized.

Closing Thought

The simplest useful shift is this:

Do not model tenants as buckets of data.

Model them as organizations with boundaries.

Those boundaries include:

data
people
roles
permissions
workflows
ownership

Once you do that, the rest of the backend design gets clearer.

You stop asking, "How do I attach tenantId to this table?"

You start asking better questions:

Who operates this organization?
Who owns it?
Who can join it?
What can each person do?
How does the active organization get resolved per request?
What should happen when a person belongs to several organizations?

That is where multi-tenant architecture starts to look like the real world.

And that is usually where the backend gets much better.

DEV Community: Oladele David

How to Model Teams Inside a Multi-Tenant Product

Table of Contents

The Gap Between "List of Users" and a Real Team

The Team Member Is Not the Same as the User

Membership Has a Lifecycle

Roles Give Membership Meaning

Predefined Roles vs Custom Permission Sets

The Invitation Flow Is Part of the Data Model

How Permission Resolution Actually Works

What the API Surface Looks Like

What I Would Avoid

1. Granting permissions the moment an invitation is sent

2. Deleting team member records on removal

3. Mixing `customPermissions` with role replacement

4. Skipping the status check in permission resolution

5. Encoding team structure in the user table

6. Letting the same role exist with different meanings in different organizations

Closing Thought

Designing Multi-Tenant Backends With Both Ownership and Team Access

Table of Contents

The Problem With Most Multi-Tenant Tutorials

The Shift: Model Organizations, Not Just Data Buckets

The Core Model

Why Ownership and Team Access Should Be Separate

Support One User Across Many Organizations

Make Organization Context Explicit Per Request

Scope Permissions to the Organization

Treat Team Management as Part of the Core Architecture

What This Model Buys You

What I Would Avoid

1. One user, one tenant

2. Treating owner as just another role

3. Global roles for tenant behavior

4. Implicit tenant resolution everywhere

5. Mixing access checks with unrelated business logic

Closing Thought

DEV Community: Oladele David

How to Model Teams Inside a Multi-Tenant Product

Table of Contents

The Gap Between "List of Users" and a Real Team

The Team Member Is Not the Same as the User

Membership Has a Lifecycle

Roles Give Membership Meaning

Predefined Roles vs Custom Permission Sets

The Invitation Flow Is Part of the Data Model

How Permission Resolution Actually Works

What the API Surface Looks Like

What I Would Avoid

1. Granting permissions the moment an invitation is sent

2. Deleting team member records on removal

3. Mixing customPermissions with role replacement

4. Skipping the status check in permission resolution

5. Encoding team structure in the user table

6. Letting the same role exist with different meanings in different organizations

Closing Thought

Designing Multi-Tenant Backends With Both Ownership and Team Access

Table of Contents

The Problem With Most Multi-Tenant Tutorials

The Shift: Model Organizations, Not Just Data Buckets

The Core Model

Why Ownership and Team Access Should Be Separate

Support One User Across Many Organizations

Make Organization Context Explicit Per Request

Scope Permissions to the Organization

Treat Team Management as Part of the Core Architecture

What This Model Buys You

What I Would Avoid

1. One user, one tenant

2. Treating owner as just another role

3. Global roles for tenant behavior

4. Implicit tenant resolution everywhere

5. Mixing access checks with unrelated business logic

Closing Thought

3. Mixing `customPermissions` with role replacement