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 toallow. 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
number_order.*, or *. Telnyx checks every statement it saves.
- Every entry must exist in the catalog. An unknown one answers
422and names the statement’sactionsfield. - 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 fornumber.deletesit 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
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