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

# How IAM Works

Every request to the Telnyx API is decided on the same questions, whatever product it reaches.

* Who is acting. A principal, proven by a credential.
* What it wants to do. An action, one per API operation.
* Which resource, and its project. Preview
* In what context, such as the source IP or how the principal signed in. Preview

## Core Concepts

| Object | What It Is |
| - | - |
| [Principal](https://developers.telnyx.com/docs/iam/principals/users.md) | Who acts. A user or a service account of one organization. |
| [Credential](https://developers.telnyx.com/docs/iam/credentials.md) | How a principal proves who it is. A user holds an API key, a session, or an OAuth token. A service account holds a service account token. |
| [Action](https://developers.telnyx.com/docs/iam/access/actions.md) | What can be done. One per API operation, named for the resource and the verb, such as `number.update`. |
| [Role](https://developers.telnyx.com/docs/iam/access/roles.md) | A named set of [statements](https://developers.telnyx.com/docs/iam/access/statements.md), each allowing or denying a list of actions. |
| [Grant](https://developers.telnyx.com/docs/iam/access/grants.md) | A role given to a principal. The only way a role reaches a principal. |
| Entitlement | What Telnyx lets the organization use at all, through its [account level and capabilities](https://developers.telnyx.com/docs/account-setup/levels-and-capabilities.md). Checked before any role. |
| [Resource](https://developers.telnyx.com/docs/iam/access/statements.md)<sup>Preview</sup> | Anything the organization owns, named `type/id`, such as `phone_number/+13125550100`. |
| [Project](https://developers.telnyx.com/docs/iam/access/projects.md)<sup>Preview</sup> | An optional boundary inside the organization that groups resources, such as `prod`. |
| [Guardrail](https://developers.telnyx.com/docs/iam/access/guardrails.md)<sup>Preview</sup> | Statements on the whole organization that every request must pass. |

## One Request

The owner configures IAM before any request. At request time, Telnyx runs its checks in a fixed order at the edge of the Telnyx API, and the first refusal answers the request, so a refused request never reaches the product. The example follows the release pipeline from the [Quick Start](https://developers.telnyx.com/docs/iam/quickstart.md) through two requests. Assigning a number is allowed, because its role allows `number.update`. Editing a SIP connection is refused at IAM, because no role allows `connection.update`.

Before a request, the organization owner configures IAM:

1. `POST /v2/iam/roles` creates a role, `test-number-provisioner`.
2. `POST /v2/iam/roles/{id}/statements` adds a statement allowing `phone_numbers.list`, `number_order.create`, and `number.update`.
3. `POST /v2/iam/grants` grants the role to the service account.
4. `PATCH /v2/iam/settings` with `{"enabled": true}` enables IAM. Changes apply within five seconds.

At request time, Telnyx runs its checks in order, and the first refusal answers the request.

| Check | Refusal |
| - | - |
| Credential: the token is valid and resolves to its principal. | `401` |
| Entitlement: the organization's account level includes the product. | `403` |
| IAM: a granted role allows the route's action and none denies it. IAM does not decide for the owner, or in an organization that has not enabled IAM. | `403` |
| Scope: an OAuth token's approved scope and the request's other requirements. | `403` |

Request 1, `PATCH /v2/phone_numbers/{id}` from the service account, needs `number.update`. Every check passes, and the product answers `200`.

Request 2, `PATCH /v2/credential_connections/{id}` from the same service account, needs `connection.update`. The credential and entitlement checks pass. IAM finds no granted role that allows the action and answers `403` with the detail `no grant allows connection.update`. The scope check never runs.

For users, the [permission groups](https://developers.telnyx.com/docs/iam/permission-groups.md) set in Mission Control Portal still apply as well, inside the product and on the categories it checks, until they retire. Service accounts, like this pipeline, are decided by their roles alone.

## Outside IAM

IAM leaves some things to other systems on purpose.

* Product credentials. SIP credentials, WebRTC tokens, Cloud Storage access keys, and Edge Compute bindings stay with their products.
* Webhooks. IAM governs requests to Telnyx. Webhooks Telnyx sends are [signed separately](https://developers.telnyx.com/docs/development/api-fundamentals/webhooks/receiving-webhooks.md).
* Entitlement and billing. What an organization can buy or use is set by its [account level](https://developers.telnyx.com/docs/account-setup/levels-and-capabilities.md), and billing ownership does not change.
* Configuration rules. A role allows or denies actions. It does not inspect what a request sets, such as a number's country.
* Assuming identities. Nobody signs in as a role, and nobody works as another person. A manager works in a [managed organization](https://developers.telnyx.com/docs/iam/access/delegations.md) as themselves.
