> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/trust/multi-tenant-organization-model.md).

# Multi-Tenant Organization Model

One platform, many organizations, hard isolation enforced at the data layer.

> **One platform, many organizations, hard isolation.** Tenant isolation is enforced at the database, not the application. Every tool call carries an org context that the gateway derives server-side and the data layer enforces from below.

***

## Why a multi-tenant model

Mediafier is shared infrastructure. A studio, a broadcaster, a brand agency, and a sports federation can all run agents through the same gateway against the same tools and the same runtimes. What separates them is the organization context: every row, every tool call, every audit entry, every credit ledger movement is bound to one organization.

The platform's promise is that the boundary holds whether the caller is a friendly engineer running a script, an autonomous agent under load, or — in the worst case — a hostile principal with a valid token trying to read another tenant's data.

***

## What an organization owns

| Owned per organization                                           | Why                                                                                               |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Member directory and roles                                       | Org admins decide who is in the org and what each member can do.                                  |
| Installed resources and credential bindings                      | Marketplace resources are platform-listed once but installed per-org with org-scoped credentials. |
| Authorization model — per-tool, per-role permissions             | Authorization decisions resolve against the org's policy.                                         |
| Rate-limit budget and per-org throttling state                   | Each org gets its own protected capacity.                                                         |
| Credit ledger and billing record                                 | All metering rolls up to the org's wallet.                                                        |
| Audit trail — every tool call, with trace ID                     | The org's auditors can reconstruct what happened on the org's behalf.                             |
| Media Library bundles, versions, files, and provenance passports | Tenant data is tenant-owned; cross-org reads are blocked at the data layer.                       |

Crossing the org boundary is not possible from the application surface — it is blocked beneath, at the database, before any handler runs.

***

## How isolation is enforced

Three concentric checks:

1. **Identity-derived org context.** The gateway resolves the caller's organization server-side from the authenticated principal. The client cannot pick the tenant via headers or body fields.
2. **Authorization scoped to that org.** The authorization stage runs against the resolved org's policy — never against a global "is this caller allowed?" check.
3. **Row isolation enforced at the data layer.** Every tenant-scoped read and write is filtered to the caller's organization at the platform's data layer — below the application. A request that somehow reached the data layer without an org filter still returns only the caller's rows.

This is the structure security reviewers are asking about when they say "RLS-enforced segregation, tenant-aware routing, and strict cross-org protection across all governed resources": Mediafier's tenant model is not a convention enforced in handlers. It is enforced from below.

***

## Membership: people in multiple organizations

Real-world operators sit in more than one organization (a partner consultant serving two clients, a freelance editor on three studio rosters, an agency operator serving several brands). The membership model accommodates that:

* A single Auth0 identity maps to one or more organization memberships.
* The active organization is selected once per session and validated server-side against the memberships Mediafier governs. A switch is a deliberate action, not an implicit one.
* The gateway uses the active organization for the entire request chain. There is no "ambient" organization that leaks across sessions.

The audit trail records the active organization for each call. A user with three memberships running three separate sessions produces three separate, organization-bound audit chains.

***

## Platform-level resources vs. tenant-level resources

Some resources are shared across the whole platform; others are tenant-private. The platform distinguishes them:

| Resource class                     | Visibility                                                                                                                              |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Platform resources                 | Implicitly available to every org.                                                                                                      |
| Marketplace-listed resources       | Visible for browsing; installation is per-org and admin-controlled.                                                                     |
| Tenant-installed resources         | Visible and callable only inside the installing org.                                                                                    |
| Tenant-authored MediaClaws         | Owned by the org that authored or installed them; not callable from another org.                                                        |
| Tenant data (Media Library, audit) | Owned by the org. Not visible to platform staff via the same surfaces; staff access is governed by separate, audited operator pathways. |

A platform listing makes a server discoverable. It does not grant runtime access until an org admin installs and binds it.

***

## What this model is not

* It is not a "shared service" model where one org's data falls into another's view by accident or by support ticket. The boundary is the data layer.
* It is not a soft convention enforced in application code that a bug could bypass. The data layer enforces it.
* It is not a single identity domain — different orgs can federate their own SSO into Auth0 and still share the gateway.

***

## Where to go next

| If you're…                                            | Read next                                                                         |
| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
| Looking at how identity is established before the org | [Identity & Authentication](/trust/identity-and-authentication.md)                |
| Auditing trust posture                                | [Audit, Observability & Compliance](/trust/audit-observability-and-compliance.md) |
| Studying the gateway's enforcement chain              | [The Gateway](/platform/gateway.md)                                               |
| Looking for enterprise procurement readiness          | [Enterprise Readiness](/trust/enterprise-readiness.md)                            |