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:

Add user to the team
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:

Add service to team's allowed_services
No re-login needed

"Cross-tenant access denied"

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

Solution:

This is expected behavior
User needs proper membership in the target tenant

"Data not appearing"

Cause: Backend not filtering by project_id.

Solution:

Verify backend uses X-Project-ID header
Check database queries include project_id filter

PreviousIntroduction NextSecurity Model

Last updated 1 month ago

Good evening

hashtagWhat is Multi-Tenancy?

hashtagBenefits

hashtagTenant Hierarchy

hashtagLevel Details

hashtagData Isolation

hashtagHow Isolation Works

hashtagIsolation Guarantees

hashtagTenant Identifiers

hashtagIdentifier Hierarchy

hashtagDenormalization

hashtagAccess Control

hashtagRole Scope

hashtagAccess Decision Flow

hashtagTeam Service Policy

hashtagPolicy Bypass

hashtagJWT Token Structure

hashtagToken Context Selection

hashtagBackend Integration

hashtagRequired Header Usage

hashtagCommon Mistakes to Avoid

hashtagBest Practices

hashtagFor Administrators

hashtagFor Developers

hashtagFor Security

hashtagTroubleshooting

hashtag"You are not a member of this team"

hashtag"Service not allowed for this team"

hashtag"Cross-tenant access denied"

hashtag"Data not appearing"

What is Multi-Tenancy?

Benefits

Tenant Hierarchy

Level Details

Data Isolation

How Isolation Works

Isolation Guarantees

Tenant Identifiers

Identifier Hierarchy

Denormalization

Access Control

Role Scope

Access Decision Flow

Team Service Policy

Policy Bypass

JWT Token Structure

Token Context Selection

Backend Integration

Required Header Usage

Common Mistakes to Avoid

Best Practices

For Administrators

For Developers

For Security

Troubleshooting

"You are not a member of this team"

"Service not allowed for this team"

"Cross-tenant access denied"

"Data not appearing"