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

# Explain and Simulate

Explain says what IAM decides for one principal and one action, and which roles are behind the decision. Simulate decides a list of requests as if the principal held other roles, without changing anything. Only the [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) sends either.

## Explain

```json POST /v2/iam/explain theme={null}
{
  "principal_type": "user",
  "principal_id": "3b52b5e6-f289-45a9-8543-3a86d0e1ae1b",
  "action": "connection.update"
}
```

```json Output theme={null}
{
  "data": {
    "action": "connection.update",
    "decision": "deny",
    "reason": "action_not_granted",
    "detail": "no role allows connection.update",
    "allowed_role_ids": [],
    "denied_role_ids": [],
    "record_type": "iam_decision"
  }
}
```

| Field | Values |
| - | - |
| `decision` | `allow`, `deny`, or `not_iam_managed`. |
| `reason` | `action_allowed`, `action_denied`, or `action_not_granted` behind an allow or a deny. `iam_disabled` when the organization has not [enabled IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md), and `no_grants` when the principal is the owner, behind `not_iam_managed`. |
| `detail` | The reason in words. |
| `allowed_role_ids` | The granted roles with an allow statement for the action. |
| `denied_role_ids` | The granted roles with a deny statement for the action. A deny wins, so both lists are filled when roles conflict. |

Explain decides from the principal's current grants, the way a request is decided. In an organization that has not enabled IAM, every explain answers `not_iam_managed` with the reason `iam_disabled`. The action is an exact ID, and a wildcard or an unknown action answers `422`. Explain does not check that the principal exists, so an unknown ID is decided like a principal without grants.

## Simulate

Simulate decides a list of requests against a set of roles instead of the principal's grants, whether or not the organization has enabled IAM. It is how an organization tests a role before granting it, or checks the requests a person sends against the roles meant to replace their current access.

```json POST /v2/iam/simulate theme={null}
{
  "principal_type": "user",
  "principal_id": "3b52b5e6-f289-45a9-8543-3a86d0e1ae1b",
  "with_role_ids": ["8c4a9715-0246-4c6f-9eca-390e13bd8af0"],
  "requests": [
    { "action": "connection.update" },
    { "action": "number.update" },
    { "action": "messaging_profile.update" }
  ]
}
```

```json Output theme={null}
{
  "data": [
    {
      "action": "connection.update",
      "decision": "allow",
      "reason": "action_allowed",
      "detail": "a role allows connection.update",
      "allowed_role_ids": ["8c4a9715-0246-4c6f-9eca-390e13bd8af0"],
      "denied_role_ids": [],
      "record_type": "iam_decision"
    },
    { "action": "number.update", "decision": "allow", ... },
    { "action": "messaging_profile.update", "decision": "deny", "reason": "action_not_granted", ... }
  ]
}
```

One decision comes back per request, in the same order, with the same fields as an explain. The owner is `not_iam_managed` in a simulate too. A simulate names at most ten distinct roles and fifty requests, and an unknown action or a role of another organization answers `422`.
