Skip to main content
One rule decides every request a user or a service account sends, once the organization has enabled IAM. Nothing is allowed until a granted role allows it, grants add up, and a deny wins.
A statement matches an action when it names the action exactly, names a wildcard that covers it, such as number_order.* for number_order.create, or names *.

The Rules

Nothing Is Allowed Until a Role Allows It

A service account reporting holds a token but no grant. Its request GET /v2/phone_numbers needs number.read.
Output
Access exists only where a grant gives it. A principal with no grant at all is refused the same way.

Grants Add Up

A user holds number-buyer, which allows number_order.create, and Read-only, which allows number.read. The user orders a number through the first grant and reads it through the second. The other grant does not need to agree, and one matching allow is enough.

A Statement Matches as a Whole

Preview A statement matches as a whole, never field by field. A role allowed in staging and a read-only role in prod never add up to a change in prod.

A Deny Beats Any Allow

The role voice-ops has an allow statement for number.* and a deny statement for number.delete. A user who holds it sends DELETE /v2/phone_numbers/+13125550100.
Output
number.* covers the delete, but the deny matches too, and a deny always wins, inside one role or across the roles a principal holds. The response names the denying roles so the owner can find the statement.

A Scope Only Narrows

Preview The scope on a user’s API key can only narrow. A request needs an allow from the grants and from the scope. A service account’s credentials carry no scope.

The Guardrail Binds Everyone

Preview A request also needs an allow from every guardrail that applies, the owner’s included.

Every Condition Must Hold

Preview Every condition in a statement must hold, and a failed condition on an allow is not a deny.

Nobody Grants More Than They Hold

Preview Granting is itself an action, and its ceiling is the granter’s own access.

A Statement Can Name Specific Resources

Preview The product that owns the resource enforces the IDs a statement names. See Statements.

The Owner Skips IAM

The organization owner’s requests are never decided by IAM. The owner holds every action, before and after IAM is enabled.

A Route Needs an Action

A route that declares no action 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.

Working in a Managed Organization Needs an Action Too

A request with an X-Managed-Account-Id header is first decided on managed_account.impersonate for the principal sending it, then on the action of its route. See Delegations.

Changes Apply Within Five Seconds

Telnyx remembers a decision for a principal and an action for five seconds. A new grant, a revoked grant, or a changed statement reaches new requests within that time.

Before and After the Rule

IAM is one step of deciding a request. Telnyx authenticates the credential first and checks the organization’s entitlement, and after an allow an OAuth token’s approved scope still narrows the request. See How IAM Works.