> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Customer Organizations

Two organizations take part, and each has its own people.

| Term | Who or What |
| - | - |
| Manager org | The organization that resells Telnyx and runs an organization for each customer. |
| Manager org owner | The [owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) of the manager org. |
| Manager org users | The users and service accounts of the manager org. |
| Managed org | An organization the manager org creates for one customer, with its own resources. |
| Customer users | The customer's own people, who are users of the managed org. |

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.<sup>Preview</sup>
* Guardrails apply in every managed org, and customer users cannot loosen them.<sup>Preview</sup>
* A manager org user who leaves loses access to every managed org at once.<sup>Preview</sup>

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](https://developers.telnyx.com/api-reference/managed-accounts/create-a-new-managed-account.md).

```json POST /v2/managed_accounts theme={null}
{
  "business_name": "Example Customer"
}
```

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](https://developers.telnyx.com/docs/iam/access/delegations.md#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.

```http theme={null}
POST /v2/messaging_profiles
Authorization: Bearer <manager org owner's API key>
X-Managed-Account-Id: f65ceda4-6522-4ad6-aede-98de83385123
Content-Type: application/json

{"name": "Appointment reminders"}
```

Preview The managed org's audit log names the manager org user behind every change. See [Audit Events](https://developers.telnyx.com/docs/iam/troubleshooting/audit-events.md).

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

```http theme={null}
POST /v2/iam/roles/{role_id}/statements
X-Managed-Account-Id: f65ceda4-6522-4ad6-aede-98de83385123

{"actions": ["message.send", "messaging_profile.read"]}
```

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](https://developers.telnyx.com/docs/iam/organization/enable-iam.md) 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.

```json POST /v2/iam/roles/{role_id}/statements theme={null}
{
  "actions": [
    "managed_account.impersonate",
    "messaging_profile.*",
    "number_order.create"
  ]
}
```

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](https://developers.telnyx.com/docs/iam/access/delegations.md#defaults-and-narrowing).

## 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](https://developers.telnyx.com/docs/iam/access/delegations.md#manager-guardrails).

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](https://developers.telnyx.com/docs/iam/access/guardrails.md#up-to-three-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.
