Skip to main content
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.

A Role

A role has a name, unique in the organization without regard to case, and an optional description.
POST /v2/iam/roles
Output
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 is an effect and a list of actions. 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.
POST /v2/iam/roles/{role_id}/statements
Output
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. 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.
PUT /v2/iam/roles/{role_id}/statements/{statement_id}

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.
POST /v2/iam/roles/{role_id}/statements
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.

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.

Deletion

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

Propagation

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