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

# Statements

A statement allows or denies a list of actions, and every role is a set of statements.

## A Statement

A statement has an effect and a list of [actions](https://developers.telnyx.com/docs/iam/access/actions.md), and lives in a [role](https://developers.telnyx.com/docs/iam/access/roles.md#statements).

```json theme={null}
{
  "effect": "deny",
  "actions": ["number.delete"]
}
```

Preview A statement also names resources, projects, and conditions.

```json theme={null}
{
  "effect": "allow",
  "actions": ["network.*"],
  "resources": ["network/*"],
  "projects": ["prod"],
  "conditions": { "ip": ["10.0.0.0/8"] }
}
```

| Field | What It Means |
| - | - |
| `effect` | `allow` or `deny`. Left out, `allow`. |
| `actions` | Action IDs, wildcards such as `number_order.*`, or `*`. |
| `resources`<sup>Preview</sup> | `type/id` patterns, such as `network/*` for every network, or specific resources such as `phone_number/+13125550100`. Left out, every resource the actions apply to. |
| `projects`<sup>Preview</sup> | [Project](https://developers.telnyx.com/docs/iam/access/projects.md) names. Left out, every project. |
| `conditions`<sup>Preview</sup> | Facts about the request, such as the source `ip`, the `auth_method` (session, OAuth, API key, service account token, short-lived token), and the `principal_type`. All of them must hold. |

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

## Three Places a Statement Takes Effect

A statement does nothing until it is attached, and it can be attached in three places.

| Place | What It Does | Where |
| - | - | - |
| [Role](https://developers.telnyx.com/docs/iam/access/roles.md) | Statements bundled into a role, which a [grant](https://developers.telnyx.com/docs/iam/access/grants.md) gives to a principal. What the principal may do. | `/v2/iam/roles`, `/v2/iam/grants` |
| [Scope](https://developers.telnyx.com/docs/iam/credentials/scoped-keys.md)<sup>Preview</sup> | Statements on a user's API key, set when it is issued. Can only narrow what that user may do. | The `scope` field of an API key |
| [Guardrail](https://developers.telnyx.com/docs/iam/access/guardrails.md)<sup>Preview</sup> | Statements on the whole organization, which every request must pass, the owner's included. | `/v2/iam/guardrail` |

A request needs an allow from a role's statements and no deny. Preview It also needs an allow from the scope, if the credential has one, and from every guardrail that applies, with no deny in any of them.

## Specific Resources, Plainly

Preview A statement can name specific resources, such as two sending numbers.

```json theme={null}
{
  "effect": "allow",
  "actions": ["message.send"],
  "resources": [
    "phone_number/+13125550100",
    "phone_number/+13125550101"
  ]
}
```

* The IDs live in the statement and nowhere else.
* Telnyx does not check that they exist. Saving a statement checks each ID's format and warns if one is not found, but saves it anyway.
* A wrong ID never matches. In an allow it grants nothing, and in a deny it protects nothing.
* The product that owns the resource does the checking. IAM allows the action and passes the list along, and the product compares it with the resource the request names, in the URL or in the body.
* Lists of specific resources are capped. For larger sets, use a project or a managed organization.
