Skip to main content
Two organizations take part, and each has its own people.
This workflow gets you:
  • The manager org owner is a superuser in every managed org, with the same full access as that org’s owner.
  • Customer users manage their own resources in their managed org, limited to the actions their roles allow. They cannot change their own access, and they never see the manager org or other managed orgs.
  • Manager org users enter managed orgs with only the actions their roles in the manager org allow.
  • Each manager org team starts with a default role in every new managed org, and one managed org can be narrowed.Preview
  • Guardrails apply in every managed org, and customer users cannot loosen them.Preview
  • A manager org user who leaves loses access to every managed org at once.Preview
A step marked Preview can be skipped, and every other step still works.

1. Create a Managed Org

In the manager org, the manager org owner creates a managed org for a customer with the Managed Accounts API.
POST /v2/managed_accounts
A managed org created without password cannot be signed into directly unless a password is set later. An org’s owner is never limited by IAM, so a managed org with no owner sign-in keeps every customer user inside their roles. Preview A delegation comes with the managed org, granting its Owner role to whoever holds Owner in the manager org. No other manager org user can see the managed org until granted.

2. Work in a Managed Org

In a managed org, the manager org owner acts with the managed org owner’s full access. A request names the managed org with the X-Managed-Account-Id header, and everything it creates or changes belongs to the managed org.
Preview The managed org’s audit log names the manager org user behind every change. See Audit Events.

3. Give Customer Users Limited Roles

In the managed org, the manager org owner writes the roles and grants for customer users. Every /v2/iam request carries the header, so the role, the grant, and the setting all belong to the managed org.
A grant with the same header gives the role to a customer user, named by the id that GET /v2/organizations/users returns for the managed org. PATCH /v2/iam/settings with the header enables IAM in the managed org. The customer user then sends messages and reads messaging profiles, and nothing else. Only an org’s owner manages IAM, so customer users cannot change any role or grant, their own included.

4. Let Manager Org Users In

In the manager org, the manager org owner gives manager org users a role that allows managed_account.impersonate. Once the manager org has enabled IAM, a manager org user needs that action to enter any managed org.
POST /v2/iam/roles/{role_id}/statements
Inside a managed org, each request from a manager org user is decided by that user’s roles in the manager org. A manager org user with this role manages messaging profiles and orders numbers in every managed org, and nothing else. The managed org’s own roles and settings never apply to manager org users.

5. Give Each Manager Org Team a Default

Preview In the manager org, the manager org owner sets the grants every delegation starts with. Manager org owners get Owner, the team that builds managed orgs gets Developer, and the support team gets Read-only. See Delegations.

6. Narrow One Managed Org

Preview In the manager org, the manager org owner narrows the delegation of one managed org whose customer runs it and wants the manager org for support only. Every manager org user gets Read-only there, the manager org owner included. Every other managed org keeps the defaults.

7. Set Guardrails Customer Users Cannot Loosen

Preview In the manager org, the manager org owner sets a guardrail on every managed org. It stops anyone in a managed org, customer users and manager org users alike, from releasing the managed org’s phone numbers, and nobody in the managed org can loosen it. See Delegations. A request a manager org user sends into a managed org also passes the manager org’s own guardrail. A rule the manager org sets for its users, such as no API keys, holds inside every managed org too. See Guardrails.

8. Offboard a Manager Org User Everywhere at Once

Preview When a user leaves the manager org, the manager org’s identity provider removes them and SCIM deletes their Telnyx user. Delegations name roles and groups, not people, so access to every managed org ends at the same moment, with nothing to edit in any managed org.