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

# Actions

An action is one operation of the Telnyx API, named for the resource it touches and what it does to it, such as `number.update`. Every role is written in actions, and every request is decided on the action its route declares.

## Naming

An action ID is `<resource>.<verb>`. The resource is the API resource, in its singular or plural form as the owning product declares it, and the verb is what the operation does.

| Action | Method | Route |
| - | - | - |
| `phone_numbers.list` | `GET` | `/v2/available_phone_numbers` |
| `number_order.create` | `POST` | `/v2/number_orders` |
| `number.update` | `PATCH` | `/v2/phone_numbers/{id}` |
| `number.delete` | `DELETE` | `/v2/phone_numbers/{id}` |
| `connection.update` | `PATCH` | `/v2/credential_connections/{id}` |
| `message.send` | `POST` | `/v2/messages` |
| `managed_account.impersonate` | Any | Any route, with the `X-Managed-Account-Id` header. See [Delegations](https://developers.telnyx.com/docs/iam/access/delegations.md). |

One action can cover several operations, such as `api_keys.read` for both the list and the single key.

## The Catalog

`GET /v2/iam/actions` lists every action, with the operations it covers.

| Parameter | What It Does |
| - | - |
| `filter[search]` | Matches the action ID, its description, or the path of an operation it covers. |
| `filter[product_id]` | Keeps the actions of one product, such as `messaging`. |
| `filter[path]` | Keeps the actions with an operation at exactly this path. |
| `filter[path][contains]` | Keeps the actions with an operation whose path contains this text. |
| `page[size]`, `page[number]` | Pagination. |

`GET /v2/iam/actions/{id}` returns one action.

```json GET /v2/iam/actions/api_keys.read theme={null}
{
  "data": {
    "id": "api_keys.read",
    "endpoints": [
      { "method": "GET", "path": "/v2/api_keys" },
      { "method": "GET", "path": "/v2/api_keys/{id}" }
    ],
    ...
  }
}
```

To find the actions behind a route, search by its path.

```json GET /v2/iam/actions?filter[path][contains]=number_orders theme={null}
{
  "data": [
    {
      "id": "number_order.create",
      "endpoints": [
        { "method": "POST", "path": "/v2/number_orders" }
      ],
      ...
    },
    {
      "id": "number_order.list",
      "endpoints": [
        { "method": "GET", "path": "/v2/number_orders" }
      ],
      ...
    },
    ...
  ]
}
```

## Wildcards

A [statement](https://developers.telnyx.com/docs/iam/access/roles.md#statements) in a role names actions exactly, or with a wildcard.

* `number_order.*` covers every action whose ID starts with `number_order.`.
* `*` covers every action.

A wildcard whose prefix matches no action is rejected like an unknown action.

## IAM's Own Actions

Managing IAM is actions too. They are declared like any other, and only the [organization owner](https://developers.telnyx.com/docs/iam/principals/organization-owner.md) may send the requests behind them, the catalog and the service account routes included. A service account token is refused on every `/v2/iam` route.

| Actions | Operations |
| - | - |
| `actions.read` | [The catalog](#the-catalog) |
| `iam_roles.read` `iam_roles.create` `iam_roles.update` `iam_roles.delete` | [Roles](https://developers.telnyx.com/docs/iam/access/roles.md) |
| `iam_role_statements.read` `iam_role_statements.create` `iam_role_statements.update` `iam_role_statements.delete` | A role's [statements](https://developers.telnyx.com/docs/iam/access/roles.md#statements) |
| `iam_grants.read` `iam_grants.create` `iam_grants.delete` | [Grants](https://developers.telnyx.com/docs/iam/access/grants.md) |
| `iam_settings.read` `iam_settings.update` | [Enable IAM](https://developers.telnyx.com/docs/iam/organization/enable-iam.md) |
| `service_accounts.read` `service_accounts.create` `service_accounts.update` `service_accounts.delete` `service_accounts.enable` `service_accounts.disable` | [Service accounts](https://developers.telnyx.com/docs/iam/principals/service-accounts.md) |
| `service_account_tokens.read` `service_account_tokens.create` `service_account_tokens.update` `service_account_tokens.delete` `service_account_tokens.activate` `service_account_tokens.deactivate` | A service account's [tokens](https://developers.telnyx.com/docs/iam/principals/service-accounts.md#tokens) |
| `iam.explain` `iam.simulate` | [Explain and simulate](https://developers.telnyx.com/docs/iam/troubleshooting/explain-and-simulate.md) |

## Routes Without an Action

Every route IAM manages declares one action. A route that declares none cannot be allowed by any role, so a principal IAM manages is refused on it, apart from a few portal, OAuth consent, and agent sign-in routes that every signed-in user may reach. Telnyx is adding an action to every customer-facing route that lacks one, and a route opens to roles once it has one.
