> 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: tool calls run in the organization derived from the caller's verified credential.

> **One platform, many organizations, one organization per tool call.** Every tool call carries an organization context that the gateway derives server-side from the caller's verified credential. Tenant-facing requests are scoped to an organization server-side, with database row-level policies on tenant data where they apply.

***

## 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 model is built so 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 — tool calls, 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; reads and writes are scoped to the owning org.                       |

For tool calls, the gateway chooses the organization from the verified credential; a header or tool argument cannot change it. Elsewhere on the platform, the organization a request acts in is resolved and authorization-checked server-side for the caller and the action.

***

## How isolation is enforced

Three layers:

* **Identity-derived org context.** The gateway resolves the caller's organization server-side from the authenticated principal. A tool call cannot pick the tenant via headers or tool arguments.
* **Authorization scoped to that org.** Authorization runs against the resolved org's policy — never against a global "is this caller allowed?" check.
* **Request scoping and row-level policies.** Tenant-scoped reads and writes are scoped to the caller's organization server-side, with database row-level policies that limit access to the owning organization where they apply.

This is the structure security reviewers are asking about when they say "RLS-enforced segregation, tenant-aware routing, and strict cross-org protection": for tool calls the tenant comes from the verified credential rather than from the caller, tenant-facing requests are scoped to an organization server-side, and database row-level policies apply where they are in place.

***

## 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.

Audit records carry the active organization for the 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 and visible to its members according to their roles. Mediafier access is limited to authorized platform operators, for support and platform operations. |

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 org's view by accident. Tenant-facing requests act in an organization context resolved and authorization-checked server-side.
* It does not let a tool call name the tenant. A header or argument that names another organization does not change the organization the call runs in.
* 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)                            |
