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

# Enable IAM

IAM is turned on per organization. Until the owner enables it, roles and grants can be written and read but decide nothing, and every request is decided by the organization's existing permissions, the ones set in Mission Control Portal and on service accounts.

> [!CAUTION]
>
> Enabling IAM before the roles and grants exist locks out every user and service account without a grant. Every principal that must keep working needs a [grant](https://developers.telnyx.com/docs/iam/access/grants.md) before the switch is turned.

## The Switch

`GET /v2/iam/settings` returns the organization's IAM settings. An organization starts disabled.

```json GET /v2/iam/settings theme={null}
{
  "data": {
    "enabled": false,
    ...
  }
}
```

`PATCH /v2/iam/settings` enables IAM.

```json PATCH /v2/iam/settings theme={null}
{
  "enabled": true
}
```

Only the [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) reads or changes the setting. A change applies to new requests within five seconds.

## What Changes

Enabling IAM is what makes roles decide. While it is off, grants exist but change nothing.

| Principal | IAM Off | IAM On |
| - | - | - |
| The owner | Everything | Everything |
| User or service account with a role | Existing permissions | Its [roles](https://developers.telnyx.com/docs/iam/access/roles.md) |
| User or service account without a role | Existing permissions | Nothing |

Working in a [managed organization](https://developers.telnyx.com/docs/iam/access/delegations.md) follows the same table.

For users, the [permission groups](https://developers.telnyx.com/docs/iam/permission-groups.md) set in Mission Control Portal still apply as well, until they retire. A user then needs both a role that allows the action and, where the product checks a category, a group that allows it. Service accounts are decided by their roles alone.

## Before Enabling

The order that leaves no gap is short.

1. Write the [roles](https://developers.telnyx.com/docs/iam/access/roles.md).
2. Grant one to each user and service account, and check the list with `GET /v2/iam/grants`.
3. Enable IAM.

## Disabling

`{"enabled": false}` returns every principal to its existing permissions within five seconds. Roles and grants stay as they are, so IAM can be enabled again without rewriting anything.
