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

# Delegations

A managed organization is an organization that another organization, its manager, runs for one of its customers, with its own bill and its own resources. Users of the manager org work inside it as themselves, and IAM decides whether each may enter and what each may do there. A delegation names who may enter, with a role each.

## Entering a Managed Organization

A request names the managed organization with the `X-Managed-Account-Id` header, as the [Managed Accounts API](https://developers.telnyx.com/api-reference/managed-accounts/lists-accounts-managed-by-the-current-user.md) describes.

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

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

Once the manager org has [enabled IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md), a user or service account of the manager org needs a granted role that allows `managed_account.impersonate` to send such a request. The request is then decided on the action of its route, `messaging_profile.create` here, for the same principal and the same roles in the manager org. The managed organization's own roles never apply to it. A refusal answers `403` like any other [denied request](https://developers.telnyx.com/docs/iam/troubleshooting/denied-requests.md).

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

The manager org's [owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) enters every managed organization with that organization owner's full access.

## A Delegation

Preview A delegation is created with each managed organization. It names the principals of the manager organization that may work there, with a role each, so a partner's people get least privilege and every change in the managed organization's audit log names the person who made it.

```json GET /v2/iam/delegations/{id} theme={null}
{
  "managed_org": "f65ceda4-6522-4ad6-aede-98de83385123",
  "grants": [
    { "principal": "org:manager/role:Owner", "role": "Owner" }
  ]
}
```

A delegation's grants name principals of the manager org as `org:<org>/group:<group>`, `org:<org>/role:<role>`, or `org:<org>` for everyone there. A new managed organization starts by granting its Owner role to whoever holds Owner in the manager org, and no other manager org user gets in until granted.

## Defaults and Narrowing

Preview `PUT /v2/iam/delegation_defaults` sets the grants every delegation starts with, and `PUT /v2/iam/delegations/{id}/grants` narrows one managed organization, down to read-only for the manager org owner if that customer asks for it.

## Manager Guardrails

Preview The manager org sets a [guardrail](https://developers.telnyx.com/docs/iam/access/guardrails.md#up-to-three-guardrails) on every managed organization, which the managed organization's own admins cannot loosen. A delegated request must pass the managed organization's guardrail and the manager org's.
