Multi-Tenant Authentication: Isolating Users and Organizations in AI Agent Systems

Why Multi-Tenancy Is Critical for AI Agent Platforms

When multiple organizations share an AI agent platform, the worst possible security failure is one tenant accessing another tenant's data. This is not a theoretical concern — tenant isolation bugs have caused major breaches at SaaS companies, exposing customer data, conversations, and proprietary agent configurations.

Multi-tenant authentication goes beyond simply verifying identity. It establishes which organization a user belongs to, ensures every database query is scoped to that organization, and prevents any request from crossing tenant boundaries — even when bugs exist in business logic.

Tenant Identification Strategies

There are three common approaches to identifying which tenant a request belongs to:

JWT Claims — embed the org_id in the JWT token. This is the most common approach and works well when users belong to a single organization.

Subdomain Routing — each tenant gets a unique subdomain like acme.agents.example.com. The middleware extracts the tenant from the hostname.

Header-Based — the client sends an X-Tenant-ID header, validated against the user's allowed organizations. Useful when users belong to multiple orgs.

For AI agent platforms, JWT claims combined with a header override for multi-org users provides the best balance of security and flexibility.

JWT Design for Multi-Tenancy

Extend your JWT payload to carry organization context:

from pydantic import BaseModel


class TenantTokenPayload(BaseModel):
    sub: str           # User ID
    org_id: str        # Primary organization
    org_role: str      # Role within the organization
    org_scopes: list[str]  # Permissions within the organization
    orgs: list[str]    # All organizations user belongs to


def create_tenant_token(user, active_org) -> str:
    membership = get_org_membership(user.id, active_org.id)
    payload = TenantTokenPayload(
        sub=user.id,
        org_id=active_org.id,
        org_role=membership.role,
        org_scopes=membership.scopes,
        orgs=[org.id for org in user.organizations],
    )
    return create_access_token(payload)

Tenant-Aware Middleware

The middleware extracts the tenant context and makes it available to every handler. It also handles organization switching for multi-org users:

from fastapi import Depends, HTTPException, Header
from typing import Optional


class TenantContext:
    def __init__(self, user_id: str, org_id: str, role: str, scopes: list[str]):
        self.user_id = user_id
        self.org_id = org_id
        self.role = role
        self.scopes = scopes


async def get_tenant_context(
    token: TenantTokenPayload = Depends(get_current_user),
    x_org_id: Optional[str] = Header(None),
) -> TenantContext:
    # Allow org switching via header
    active_org = x_org_id or token.org_id

    # Verify user actually belongs to the requested org
    if active_org not in token.orgs:
        raise HTTPException(
            status_code=403,
            detail="You do not belong to this organization",
        )

    # If switching orgs, fetch the correct role and scopes
    if active_org != token.org_id:
        membership = await get_org_membership(token.sub, active_org)
        return TenantContext(
            user_id=token.sub,
            org_id=active_org,
            role=membership.role,
            scopes=membership.scopes,
        )

    return TenantContext(
        user_id=token.sub,
        org_id=token.org_id,
        role=token.org_role,
        scopes=token.org_scopes,
    )

Row-Level Data Isolation

The most important layer of defense. Every database query must be scoped to the current tenant. Build this into your repository layer so individual endpoints cannot accidentally skip the filter:

from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession


class TenantRepository:
    def __init__(self, session: AsyncSession, tenant: TenantContext):
        self.session = session
        self.tenant = tenant

    async def get_agents(self, limit: int = 50, offset: int = 0):
        query = (
            select(Agent)
            .where(Agent.org_id == self.tenant.org_id)  # Always filtered
            .limit(limit)
            .offset(offset)
        )
        result = await self.session.execute(query)
        return result.scalars().all()

    async def get_agent_by_id(self, agent_id: str):
        query = (
            select(Agent)
            .where(Agent.id == agent_id)
            .where(Agent.org_id == self.tenant.org_id)  # Cross-tenant prevention
        )
        result = await self.session.execute(query)
        agent = result.scalar_one_or_none()
        if not agent:
            raise HTTPException(status_code=404, detail="Agent not found")
        return agent

    async def create_agent(self, data: dict):
        agent = Agent(
            **data,
            org_id=self.tenant.org_id,  # Stamp org on creation
            created_by=self.tenant.user_id,
        )
        self.session.add(agent)
        await self.session.commit()
        return agent

Notice that the org_id filter appears on every query. Even if a user somehow guesses another tenant's agent ID, the WHERE clause prevents access. The create_agent method stamps the org_id from the tenant context, never from user input.

Database-Level Enforcement with PostgreSQL RLS

For defense in depth, enable Row Level Security so the database itself rejects cross-tenant access, even if application code has a bug:

ALTER TABLE agents ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON agents
    USING (org_id = current_setting('app.current_org_id'));

Set the session variable at the start of each request:

@app.middleware("http")
async def set_tenant_rls(request: Request, call_next):
    tenant = request.state.tenant
    async with db.session() as session:
        await session.execute(
            text("SET LOCAL app.current_org_id = :org_id"),
            {"org_id": tenant.org_id},
        )
    return await call_next(request)

FAQ

How do I prevent IDOR (Insecure Direct Object Reference) across tenants?

Always include the org_id filter in every database query, not just the resource ID. Use UUIDs instead of sequential IDs so attackers cannot enumerate resources. Build the tenant filter into your repository base class so individual endpoints inherit it automatically. Database-level RLS provides an additional safety net.

Should I use separate databases per tenant or a shared database with row-level filtering?

For most AI agent platforms, a shared database with row-level filtering is the right choice. It is simpler to manage, migrate, and back up. Separate databases make sense only for enterprise customers with strict compliance requirements (like data residency). You can start shared and offer dedicated databases as a premium tier.

How do I handle users who belong to multiple organizations?

Include the full list of organization IDs in the JWT orgs claim but set one as the active org_id. Support an X-Org-ID header to switch the active organization. Validate that the requested org is in the user's allowed list. Fetch the correct role and scopes for the target organization dynamically.

---

#MultiTenant #Authentication #FastAPI #AIAgents #DataIsolation #SaaSSecurity #AgenticAI #LearnAI #AIEngineering