Multi-Tenancy

Atlas Auth Guard implements a comprehensive multi-tenant architecture that provides complete data isolation between organizations, teams, and projects.

---

What is Multi-Tenancy?

Multi-tenancy allows a single instance of the application to serve multiple customers (tenants) while keeping their data completely isolated.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    ATLAS AUTH GUARD - SINGLE INSTANCE                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐              │
│  │  Organization A │  │  Organization B │  │  Organization C │              │
│  │  (Turing)       │  │  (Partner Co)   │  │  (Client Inc)   │              │
│  │                 │  │                 │  │                 │              │
│  │  ┌───────────┐  │  │  ┌───────────┐  │  │  ┌───────────┐  │              │
│  │  │  Team 1   │  │  │  │  Team X   │  │  │  │  Team P   │  │              │
│  │  │  Team 2   │  │  │  │  Team Y   │  │  │  │  Team Q   │  │              │
│  │  │  Team 3   │  │  │  └───────────┘  │  │  └───────────┘  │              │
│  │  └───────────┘  │  │                 │  │                 │              │
│  │                 │  │                 │  │                 │              │
│  │  🔒 ISOLATED    │  │  🔒 ISOLATED    │  │  🔒 ISOLATED    │              │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘              │
│                                                                              │
│  ═══════════════════════════════════════════════════════════════════════    │
│                     SHARED INFRASTRUCTURE                                    │
│  ═══════════════════════════════════════════════════════════════════════    │
│                                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Database   │  │   Cache     │  │  Auth Guard │  │  Backend    │        │
│  │  (Postgres) │  │   (Redis)   │  │  (FastAPI)  │  │  Services   │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Benefits

Benefit	Description
Cost Efficiency	Shared infrastructure reduces operational costs
Scalability	Single deployment scales for all tenants
Maintenance	One codebase, one deployment, easier updates
Security	Logical isolation enforced at every layer

---

Tenant Hierarchy

Atlas Auth Guard uses a three-level tenant hierarchy:

┌─────────────────────────────────────────────────────────────────────────────┐
│                        TENANT HIERARCHY                                      │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌─────────────────────────────────────┐
                    │           ORGANIZATION              │
                    │                                     │
                    │  • Root tenant                      │
                    │  • Billing entity                   │
                    │  • SSO/MFA policies                 │
                    │  • All users belong here            │
                    │                                     │
                    │  Example: "Turing"                  │
                    └─────────────────┬───────────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
              ▼                       ▼                       ▼
   ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
   │      TEAM        │    │      TEAM        │    │      TEAM        │
   │                  │    │                  │    │                  │
   │  • Sub-tenant    │    │  • Sub-tenant    │    │  • Sub-tenant    │
   │  • User groups   │    │  • User groups   │    │  • User groups   │
   │  • Service policy│    │  • Service policy│    │  • Service policy│
   │                  │    │                  │    │                  │
   │  "Engineering"   │    │  "Data Science"  │    │  "Platform"      │
   └────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘
            │                       │                       │
      ┌─────┴─────┐           ┌─────┴─────┐           ┌─────┴─────┐
      │           │           │           │           │           │
      ▼           ▼           ▼           ▼           ▼           ▼
  ┌───────┐  ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐   ┌───────┐
  │PROJECT│  │PROJECT│   │PROJECT│   │PROJECT│   │PROJECT│   │PROJECT│
  │       │  │       │   │       │   │       │   │       │   │       │
  │LLM API│  │Rater  │   │ML Exp │   │Research│  │Guard  │   │Infra  │
  │       │  │       │   │       │   │       │   │       │   │       │
  │API Key│  │API Key│   │API Key│   │API Key│   │API Key│   │API Key│
  │Data   │  │Data   │   │Data   │   │Data   │   │Data   │   │Data   │
  └───────┘  └───────┘   └───────┘   └───────┘   └───────┘   └───────┘

Level Details

Level	Purpose	Key Features
Organization	Root tenant, billing entity	SSO settings, MFA policies, user domain
Team	Logical user grouping	Service access policy, member management
Project	Isolated workspace	Own API key, data isolation, metadata

---

Data Isolation

Data isolation is enforced at every layer to ensure tenants cannot access each other's data.

How Isolation Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                     DATA ISOLATION ENFORCEMENT                               │
└─────────────────────────────────────────────────────────────────────────────┘

  Request from User (Engineering Team, LLM API Project)
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ LAYER 1: JWT TOKEN                                                       │
  │                                                                          │
  │ Token contains:                                                          │
  │   org_id: "4047160a-abb2-497c-bf0c-3f4ab7cb0b16"                         │
  │   team_id: "ab2785b2-b5d0-4926-92fb-00aae5ec860a"                        │
  │   project_id: "5ac942ba-0290-48a7-be6e-7ea58cd40b68"                     │
  │                                                                          │
  │ ⚠️ User CANNOT modify these values (signed token)                        │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ LAYER 2: AUTH GUARD VALIDATION                                           │
  │                                                                          │
  │ 1. Validate JWT signature                                                │
  │ 2. Verify user is member of team                                         │
  │ 3. Verify user is member of project                                      │
  │ 4. Check team service policy                                             │
  │                                                                          │
  │ ❌ Any check fails → 403 Forbidden                                        │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ LAYER 3: HEADER INJECTION                                                │
  │                                                                          │
  │ Auth Guard injects trusted headers:                                      │
  │   X-Org-ID: 4047160a-abb2-497c-bf0c-3f4ab7cb0b16                         │
  │   X-Team-ID: ab2785b2-b5d0-4926-92fb-00aae5ec860a                        │
  │   X-Project-ID: 5ac942ba-0290-48a7-be6e-7ea58cd40b68                     │
  │                                                                          │
  │ ⚠️ Backend trusts these headers (set by Auth Guard only)                 │
  └─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ LAYER 4: BACKEND DATA FILTERING                                          │
  │                                                                          │
  │ Backend MUST filter all queries:                                         │
  │                                                                          │
  │   SELECT * FROM objects                                                  │
  │   WHERE project_id = '5ac942ba-...'  ← From X-Project-ID header          │
  │   AND team_id = 'ab2785b2-...'       ← Additional filter                 │
  │                                                                          │
  │ ⚠️ Returns ONLY data for this project                                    │
  └─────────────────────────────────────────────────────────────────────────┘

Isolation Guarantees

Guarantee	Implementation
Cross-Org Isolation	org_id checked at every request
Cross-Team Isolation	team_id validated against membership
Cross-Project Isolation	project_id injected in headers, backend filters
API Key Isolation	API keys bound to specific project
Data Isolation	All database queries filtered by tenant IDs

---

Tenant Identifiers

Every piece of data in the system is tagged with tenant identifiers:

Identifier Hierarchy

┌─────────────────────────────────────────────────────────────────────────────┐
│                     TENANT IDENTIFIER FLOW                                   │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌──────────────────────────────────────────────────────────────────────────┐
  │ USER                                                                      │
  │ ────                                                                      │
  │ user_id: e9f7fca6-65d3-4be0-8374-07870b789a28                             │
  │ org_id:  4047160a-abb2-497c-bf0c-3f4ab7cb0b16  ← User belongs to org     │
  └──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │ TEAM MEMBERSHIP                                                           │
  │ ───────────────                                                           │
  │ user_id: e9f7fca6-...                                                     │
  │ team_id: ab2785b2-b5d0-4926-92fb-00aae5ec860a  ← User is member of team  │
  │ org_id:  4047160a-...                          ← Denormalized for queries │
  │ role:    team_admin                                                       │
  └──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │ PROJECT MEMBERSHIP                                                        │
  │ ──────────────────                                                        │
  │ user_id:    e9f7fca6-...                                                  │
  │ project_id: 5ac942ba-0290-48a7-be6e-7ea58cd40b68  ← User's project       │
  │ team_id:    ab2785b2-...                          ← Denormalized         │
  │ org_id:     4047160a-...                          ← Denormalized         │
  │ role:       editor                                                        │
  └──────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │ PROJECT DATA (in backend services)                                        │
  │ ────────────────────────────────────                                      │
  │ object_id:  abc123                                                        │
  │ project_id: 5ac942ba-...  ← Data belongs to project                       │
  │ team_id:    ab2785b2-...  ← Data belongs to team                          │
  │ org_id:     4047160a-...  ← Data belongs to org                           │
  │ data:       { ... }                                                       │
  └──────────────────────────────────────────────────────────────────────────┘

Denormalization

We denormalize org_id and team_id into child records for efficient querying:

Record Type	Contains
Team	org_id
Project	org_id, team_id
User Team Role	org_id
User Project Role	org_id, team_id
API Key	org_id, team_id, project_id
Backend Data	org_id, team_id, project_id

This allows efficient queries like:

-- Get all projects in an organization (fast!)
SELECT * FROM projects WHERE org_id = '...'

-- Get all users in a team (fast!)
SELECT * FROM user_team_roles WHERE team_id = '...'

---

Access Control

Multi-tenancy integrates with RBAC (Role-Based Access Control):

Role Scope

┌─────────────────────────────────────────────────────────────────────────────┐
│                     ROLE SCOPE BY TENANT LEVEL                               │
└─────────────────────────────────────────────────────────────────────────────┘

  GLOBAL SCOPE (Platform-wide)
  ═══════════════════════════
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ super_admin                                                              │
  │ • Can access ALL organizations                                           │
  │ • Bypasses ALL tenant checks                                             │
  │ • Platform operators only                                                │
  └─────────────────────────────────────────────────────────────────────────┘

  ORGANIZATION SCOPE
  ══════════════════
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ org_admin                                                                │
  │ • Can access ALL teams in their org                                      │
  │ • Can access ALL projects in their org                                   │
  │ • Bypasses team/project membership checks                                │
  │ • Cannot access other organizations                                      │
  └─────────────────────────────────────────────────────────────────────────┘

  TEAM SCOPE
  ══════════
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ team_admin / team_member                                                 │
  │ • Can access their team only                                             │
  │ • team_admin: Can access all projects in team                            │
  │ • team_member: Can access assigned projects only                         │
  │ • Subject to team service policy                                         │
  └─────────────────────────────────────────────────────────────────────────┘

  PROJECT SCOPE
  ═════════════
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ project_admin / editor / viewer                                          │
  │ • Can access their project only                                          │
  │ • Subject to team service policy                                         │
  │ • Data filtered by project_id                                            │
  └─────────────────────────────────────────────────────────────────────────┘

Access Decision Flow

User requests /v1/llm/generate
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: Is user super_admin?                                                │
│         YES → ALLOW (bypass all checks)                                     │
│         NO  → Continue                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 2: Is user org_admin for the org in JWT?                               │
│         YES → ALLOW (bypass team/project checks)                            │
│         NO  → Continue                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 3: Is user member of team in JWT?                                      │
│         NO  → DENY (403 Forbidden)                                          │
│         YES → Continue                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 4: Is "llm" service in team's allowed_services?                        │
│         NO  → DENY (403 Service not allowed)                                │
│         YES → Continue                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 5: Is user member of project in JWT (or team_admin)?                   │
│         NO  → DENY (403 Not project member)                                 │
│         YES → ALLOW                                                         │
└─────────────────────────────────────────────────────────────────────────────┘

---

Team Service Policy

Each team has a service access policy that controls which backend services team members can use:

┌─────────────────────────────────────────────────────────────────────────────┐
│                     TEAM SERVICE POLICY                                      │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────┐
  │ TEAM: Engineering                                                        │
  │                                                                          │
  │ allowed_services:                                                        │
  │   ✅ llm                                                                  │
  │   ✅ auto-rater                                                           │
  │   ✅ atlas-al-oss-svc                                                     │
  │   ✅ cot                                                                  │
  │   ❌ analytics (not in list)                                              │
  │   ❌ billing (not in list)                                                │
  │                                                                          │
  │ Effect:                                                                  │
  │ • Engineering team members can call llm, auto-rater, oss, cot            │
  │ • Engineering team members CANNOT call analytics or billing              │
  │ • Even if user is project_admin, they're still limited to these services │
  └─────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────┐
  │ TEAM: Data Science                                                       │
  │                                                                          │
  │ allowed_services:                                                        │
  │   ✅ llm                                                                  │
  │   ✅ analytics                                                            │
  │   ❌ auto-rater (not in list)                                             │
  │   ❌ atlas-al-oss-svc (not in list)                                       │
  │                                                                          │
  │ Effect:                                                                  │
  │ • Data Science team can only use llm and analytics                       │
  │ • Different teams have different service access                          │
  └─────────────────────────────────────────────────────────────────────────┘

Policy Bypass

Role	Bypasses Team Policy?
super_admin	✅ Yes - Platform-wide access
org_admin	✅ Yes - Organization-wide access
team_admin	❌ No - Still subject to team policy
team_member	❌ No - Subject to team policy
project_admin	❌ No - Subject to team policy
editor	❌ No - Subject to team policy
viewer	❌ No - Subject to team policy

---

JWT Token Structure

The JWT token contains the user's tenant context:

{
  "sub": "e9f7fca6-65d3-4be0-8374-07870b789a28",
  "email": "[email protected]",
  "name": "Alice Smith",

  "https://atlas.turing.com/org_id": "4047160a-abb2-497c-bf0c-3f4ab7cb0b16",
  "https://atlas.turing.com/org_name": "Turing",

  "https://atlas.turing.com/team_id": "ab2785b2-b5d0-4926-92fb-00aae5ec860a",
  "https://atlas.turing.com/team_name": "Engineering",

  "https://atlas.turing.com/project_id": "5ac942ba-0290-48a7-be6e-7ea58cd40b68",
  "https://atlas.turing.com/project_name": "LLM API",

  "https://atlas.turing.com/global_role": "member",
  "https://atlas.turing.com/team_role": "team_admin",
  "https://atlas.turing.com/project_role": "editor",

  "https://atlas.turing.com/permissions": [
    "read:team",
    "write:team",
    "read:project",
    "write:project",
    "execute:services"
  ],

  "iat": 1766232057,
  "exp": 1766318457
}

Token Context Selection

When a user logs in, they select their team and project context:

┌─────────────────────────────────────────────────────────────────────────────┐
│                     LOGIN CONTEXT SELECTION                                  │
└─────────────────────────────────────────────────────────────────────────────┘

  User: [email protected]

  Available Teams:
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ ○ Engineering (team_admin)                                               │
  │ ○ Data Science (member)                                                  │
  │ ● Platform (team_admin)  ← Selected                                      │
  └─────────────────────────────────────────────────────────────────────────┘

  Available Projects (in Platform team):
  ┌─────────────────────────────────────────────────────────────────────────┐
  │ ● Auth Guard (project_admin)  ← Selected                                 │
  │ ○ Infrastructure (editor)                                                │
  └─────────────────────────────────────────────────────────────────────────┘

  Generated JWT contains:
  • team_id: Platform team ID
  • project_id: Auth Guard project ID
  • team_role: team_admin
  • project_role: project_admin

---

Backend Integration

Backend services must properly handle multi-tenancy:

Required Header Usage

from fastapi import Header, HTTPException

@app.get("/objects")
async def list_objects(
    x_org_id: str = Header(...),
    x_team_id: str = Header(...),
    x_project_id: str = Header(...),
    x_user_id: str = Header(...),
):
    """
    List objects - MUST filter by tenant IDs.

    Headers are injected by Auth Guard and can be trusted.
    """
    # CRITICAL: Always filter by project_id at minimum
    objects = await db.query(Object).filter(
        Object.project_id == x_project_id,
        # Optionally add team/org filters for extra safety
        Object.team_id == x_team_id,
        Object.org_id == x_org_id,
    ).all()

    return objects


@app.post("/objects")
async def create_object(
    data: ObjectCreate,
    x_org_id: str = Header(...),
    x_team_id: str = Header(...),
    x_project_id: str = Header(...),
    x_user_id: str = Header(...),
):
    """
    Create object - MUST tag with tenant IDs.
    """
    # CRITICAL: Always set tenant IDs on new records
    new_object = Object(
        **data.dict(),
        org_id=x_org_id,      # Set org
        team_id=x_team_id,    # Set team
        project_id=x_project_id,  # Set project
        created_by=x_user_id,
    )

    await db.add(new_object)
    return new_object

Common Mistakes to Avoid

❌ Wrong	✅ Correct
SELECT * FROM objects	SELECT * FROM objects WHERE project_id = ?
Ignoring X-Project-ID header	Always filter by X-Project-ID
Trusting user-provided project_id	Only trust headers from Auth Guard
Not setting tenant IDs on create	Always set org_id, team_id, project_id

---

Best Practices

For Administrators

Practice	Reason
One team per department	Clear ownership
Meaningful team names	Easy identification
Review team policies regularly	Ensure appropriate access
Audit cross-team access	Detect anomalies

For Developers

Practice	Reason
Always filter by project_id	Ensure data isolation
Trust only Auth Guard headers	Security
Log tenant context	Audit trail
Test with multiple tenants	Verify isolation

For Security

Practice	Reason
Validate tenant IDs	Prevent injection
Monitor cross-tenant attempts	Detect attacks
Regular access reviews	Remove stale access
Encrypt tenant data	Defense in depth

---

Troubleshooting

"You are not a member of this team"

Cause: User's JWT contains a team_id they're not a member of.

Solution:

1. Add user to the team

2. User re-logs in to get new JWT

"Service not allowed for this team"

Cause: Team's service policy doesn't include the requested service.

Solution:

1. Add service to team's allowed_services

2. No re-login needed

"Cross-tenant access denied"

Cause: User trying to access resource from different org/team.

Solution:

1. This is expected behavior

2. User needs proper membership in the target tenant

"Data not appearing"

Cause: Backend not filtering by project_id.

Solution:

1. Verify backend uses X-Project-ID header

2. Check database queries include project_id filter