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

# Roles

A role is a named set of statements, each allowing or denying a list of actions. An organization writes its own roles and gives them to users and service accounts with [grants](https://developers.telnyx.com/docs/iam/access/grants.md).

## A Role

A role has a name, unique in the organization without regard to case, and an optional description.

```json POST /v2/iam/roles theme={null}
{
  "name": "test-number-provisioner",
  "description": "Searches, orders and assigns test numbers"
}
```

```json Output theme={null}
{
  "data": {
    "id": "8c4a9715-0246-4c6f-9eca-390e13bd8af0",
    "name": "test-number-provisioner",
    ...
  }
}
```

`GET /v2/iam/roles` lists the organization's roles, newest first, and `GET /v2/iam/roles/{id}` returns one. `PATCH /v2/iam/roles/{id}` changes the name or the description. A role of another organization answers `404`.

A new role allows nothing until it has a statement.

## Statements

A [statement](https://developers.telnyx.com/docs/iam/access/statements.md) is an effect and a list of [actions](https://developers.telnyx.com/docs/iam/access/actions.md). The effect defaults to `allow`. A role's statements live under `/v2/iam/roles/{role_id}/statements`.

Preview A statement also names [resources, projects, and conditions](https://developers.telnyx.com/docs/iam/access/statements.md).

```json POST /v2/iam/roles/{role_id}/statements theme={null}
{
  "actions": [
    "phone_numbers.list",
    "number_order.create",
    "number.update"
  ]
}
```

```json Output theme={null}
{
  "data": {
    "id": "f319340f-b0f0-4c3e-a0e5-d5f65bc1bc4a",
    "effect": "allow",
    "actions": [
      "phone_numbers.list",
      "number_order.create",
      "number.update"
    ],
    ...
  }
}
```

Each entry is an exact action ID, a wildcard such as `number_order.*`, or `*`. Telnyx checks every statement it saves.

* Every entry must exist in the [catalog](https://developers.telnyx.com/docs/iam/access/actions.md#the-catalog). An unknown one answers `422` and names the statement's `actions` field.
* A statement holds at least one action. Duplicates are dropped.
* An action may appear in several statements of a role, which is how an allow for `number.*` and a deny for `number.delete` sit side by side.

`GET /v2/iam/roles/{role_id}/statements` lists a role's statements, oldest first. `PUT /v2/iam/roles/{role_id}/statements/{statement_id}` replaces a statement, and takes both `effect` and `actions`. `DELETE /v2/iam/roles/{role_id}/statements/{statement_id}` removes one.

```json PUT /v2/iam/roles/{role_id}/statements/{statement_id} theme={null}
{
  "effect": "allow",
  "actions": [
    "number_order.*",
    "phone_numbers.list",
    "number.update"
  ]
}
```

## Deny Statements

A statement with `"effect": "deny"` refuses its actions to everyone who holds the role, whatever other statements or other roles allow. A deny is how a broad role keeps one thing off limits.

```json POST /v2/iam/roles/{role_id}/statements theme={null}
{
  "effect": "deny",
  "actions": ["number.delete"]
}
```

With an allow statement for `number.*` and this deny statement in the same role, the role updates numbers and never releases one. See [Evaluation Sequence](https://developers.telnyx.com/docs/iam/troubleshooting/evaluation-sequence.md).

## Ready-Made Roles

Preview Telnyx provides ready-made roles and keeps their statements up to date as products add actions. An organization grants them like its own roles. A role the organization wrote never changes.

| Role | What It Holds |
| - | - |
| Owner | Every action in every project. The role of the user who created the organization, grantable to a second owner. |
| Org Admin | Runs IAM for the organization, roles, grants, and settings included. |
| Project Admin | Runs access inside one [project](https://developers.telnyx.com/docs/iam/access/projects.md). |
| Developer | Builds with every product, without changing IAM or billing. |
| Read-only | Reads everything and changes nothing. |
| Billing Viewer | Balance and invoices. |
| Messaging Sender | Sends messages. |

## Deletion

`DELETE /v2/iam/roles/{id}` deletes the role and its statements. It fails while any grant names the role.

```json Output wrap theme={null}
{
  "errors": [
    {
      "code": "10021",
      "detail": "The role is granted to one or more principals. Revoke its grants first.",
      ...
    }
  ]
}
```

## Propagation

A change to a role or its statements applies to new requests from every principal that holds it within five seconds.
