> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engagefabric.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Tenancy

> Learn how EngageFabric multi-tenancy isolates data per organization. Understand tenant architecture, project scoping, and row-level security.

EngageFabric is built as a multi-tenant SaaS platform, allowing you to manage multiple applications and projects from a single account.

## Architecture Overview

```mermaid theme={null}
graph TD
    T[Tenant / Organization] --> P1[Project A]
    T --> P2[Project B]
    P1 --> PL1[Players]
    P1 --> Q1[Quests]
    P1 --> L1[Leaderboards]
    P2 --> PL2[Players]
    P2 --> Q2[Quests]
    P2 --> L2[Leaderboards]
```

Each tenant has isolated projects, and each project has its own players, quests, and leaderboards. Data never crosses project boundaries.

## Hierarchy

### Tenants

A **Tenant** represents your organization or company account. Each tenant can have:

* Multiple team members with different roles
* Multiple projects for different applications
* Shared billing and subscription management

### Projects

A **Project** represents a single application or game. Each project has:

* Isolated player data
* Independent configuration (rules, quests, adventures)
* Separate API keys
* Own leaderboards and lobbies

<Info>
  Players, quests, and all gamification data are **completely isolated** between projects.
  This allows you to run multiple games or applications from a single tenant account.
</Info>

## Data Isolation

EngageFabric ensures complete data isolation between projects:

| Data Type    | Isolation Level |
| ------------ | --------------- |
| Players      | Project-level   |
| Events       | Project-level   |
| Quests       | Project-level   |
| Leaderboards | Project-level   |
| Rules        | Project-level   |
| API Keys     | Project-level   |

## Team Roles

Manage team access with role-based permissions:

| Role          | Description   | Permissions                           |
| ------------- | ------------- | ------------------------------------- |
| **Owner**     | Tenant owner  | Full access, billing, delete tenant   |
| **Admin**     | Administrator | Manage projects, users, settings      |
| **Designer**  | Game designer | Create/edit rules, quests, adventures |
| **Developer** | Developer     | API access, read configs              |
| **Viewer**    | Read-only     | View dashboards and analytics         |

## Best Practices

<AccordionGroup>
  <Accordion title="Separate environments">
    Create separate projects for development, staging, and production environments.
    Use test API keys (`ef_test_`) for non-production.
  </Accordion>

  <Accordion title="One project per game">
    Each game or application should have its own project to maintain clean data isolation.
  </Accordion>

  <Accordion title="Use meaningful names">
    Name projects clearly (e.g., "MyGame-Production", "MyGame-Staging") for easy identification.
  </Accordion>
</AccordionGroup>

## API Context

All API requests are scoped to a project via the API key:

```bash theme={null}
# This request operates within the project associated with the API key
curl -X GET "https://api.engagefabric.com/api/v1/players" \
  -H "X-API-Key: ef_live_your-project-key"
```

You don't need to specify project IDs in most requests - the API key determines the context.