# Root Orgs, Sub-orgs, and Resource Sharing

Monad organizes work into a hierarchy of organizations. A **root org** sits at the top, **sub-orgs** are organizations nested underneath it, **role-based access control (RBAC)** governs what each user can do inside a single org, and **resource sharing** lets a root org share resources with its sub-orgs. This guide explains how those pieces relate; each has its own reference documentation, linked inline.

## The organization hierarchy

A **sub-org** (sub-organization) is a Monad organization nested underneath your root org — the same relationship the docs also describe as a top-level organization and its child organizations. Each org is an isolation boundary: connectors, pipelines, and secrets belong to one org, and API calls are scoped to that org, so a credential for one org cannot reach another's data.

The mental model:

- **Hierarchy** is the shape — a root org with sub-orgs beneath it.
- **RBAC** governs permissions *within* an org.
- **Resource sharing** is a one-way link *between* a singular root org and its sub-orgs.

### Which organization ID to use

A sub-org has its own organization ID, separate from its root org's. Wherever the docs ask for your Monad organization ID — for example as the `ExternalId` in an AWS role's trust policy — use the ID of the org you are working in. If you work in a sub-org, that is the sub-org's ID, not the root org's.

In the API, an organization with a non-empty `parent_organization_id` is a sub-org; the field holds its root org's ID.

For how this maps to API scoping and multi-tenant setups, see [Auth & Tenancy](/docs/sdks/embed/auth-tenancy).

## Roles and access control

Every organization uses RBAC, and **roles are scoped to a single organization — each user has exactly one role per org**. Roles are made up of granular permissions grouped by resource.

Four protected default roles ship with every org and cannot be edited or deleted:

- **System Administrator** — full access, including managing users, roles, org settings, and SSO.
- **Contributor** — read/write on pipelines, inputs, outputs, transforms, enrichments, secrets, API keys, and alert rules, and can view org logs and metrics; cannot manage users, roles, settings, or SSO.
- **Reader** — read-only across those resources.
- **Data Sender** — publish-only: can send data to a pipeline's ingest endpoint (`pipeline:data:write`) and nothing else. Intended for systems that ship data into Monad.

You can also create **custom roles** from any subset of permissions, with one guardrail: you can only grant permissions your own role already has, so a role can never escalate privileges. API keys are assigned a role too, using the same permission system. The full per-permission matrix and user-management details are in [Organization RBAC](/docs/guides/organization-rbac).

## Sharing resources across the hierarchy

Resource sharing lets a root org make certain resources available to its sub-orgs. Sharing flows **one way — from a root org down to its sub-orgs** — and a sub-org cannot re-share what it receives.

- **What can be shared:** inputs, outputs, transforms, enrichments, and secrets.
- **Read-only to the recipient:** a sub-org can use a shared resource in its pipelines but cannot edit or delete it; only the owning org can change it. Sharing a secret lets a sub-org reference a credential without ever seeing its value.
- **In-use protection:** you cannot unshare a resource while a sub-org still has something using it.
- **Share with future sub-orgs:** an option to automatically share with sub-orgs added later grants access to sub-orgs created after the setting is enabled.

Step-by-step instructions and worked scenarios — centrally managed credentials, a standard destination for every sub-org, day-one access for new sub-orgs, and winding access down safely — are in [Resource Sharing](/docs/guides/resource-sharing).

## Related

- [Organization RBAC](/docs/guides/organization-rbac)
- [Resource Sharing](/docs/guides/resource-sharing)
- [API Keys](/docs/guides/api-keys) · [Secrets](/docs/guides/secrets)
- [Auth & Tenancy](/docs/sdks/embed/auth-tenancy)