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

# Grants

A grant gives one role to one principal. It is the only way a role reaches a user or a service account, and nothing attaches to a principal directly. A principal can hold up to ten roles, one grant each, and their statements add up.

## A Grant

A grant names a [role](https://developers.telnyx.com/docs/iam/access/roles.md) of the organization and a principal of the same organization.

```json POST /v2/iam/grants theme={null}
{
  "role_id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
  "principal_type": "service_account",
  "principal_id": "e6cd1ff6-6e3a-4ff3-88d5-2234142c1df2"
}
```

```json Output theme={null}
{
  "data": {
    "id": "b4c4bb86-5a8f-4414-b011-93592888edf7",
    "record_type": "iam_grant",
    ...
  }
}
```

| Field | Value |
| - | - |
| `role_id` | A role of the organization. |
| `principal_type` | `user`, `service_account`, or `group`<sup>Preview</sup> for a [group](https://developers.telnyx.com/docs/iam/principals/groups.md) of the identity provider. |
| `principal_id` | The [user's](https://developers.telnyx.com/docs/iam/principals/users.md) ID or the [service account's](https://developers.telnyx.com/docs/iam/principals/service-accounts.md) ID. |
| `projects`<sup>Preview</sup> | The [projects](https://developers.telnyx.com/docs/iam/access/projects.md) the role applies in. Left out, every project. |

Preview In a [managed organization](https://developers.telnyx.com/docs/iam/access/delegations.md#a-delegation), a delegation's grants name principals of the manager organization.

Telnyx refuses these grants with `422` and names the field at fault.

* A principal that does not exist in the organization. A user or service account of another organization is reported the same way.
* The [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md), who holds every action already.
* A role the principal already holds.
* An eleventh grant for the same principal.

## Listing

`GET /v2/iam/grants` lists the organization's grants, newest first, and filters by role or by principal.

```json GET /v2/iam/grants?filter[principal_id]={service_account_id} theme={null}
{
  "data": [
    {
      "id": "b4c4bb86-5a8f-4414-b011-93592888edf7",
      "role_id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
      ...
    }
  ],
  "meta": { "total_results": 1, ... }
}
```

`filter[role_id]` lists everyone who holds a role, which is what to check before deleting it.

## Revocation

`DELETE /v2/iam/grants/{id}` revokes the grant and returns it. The principal loses the role's statements for new requests within five seconds.

Once the organization has [enabled IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md), a principal whose last grant is revoked is refused every action until it holds a role again.
