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