Skip to main content
A grant gives one role to one principal. It is the only way a role reaches a user or a service account, and nothing attaches to a principal directly. A principal can hold up to ten roles, one grant each, and their statements add up.

A Grant

A grant names a role of the organization and a principal of the same organization.
POST /v2/iam/grants
Output
Preview In a managed organization, a delegation’s grants name principals of the manager organization. Telnyx refuses these grants with 422 and names the field at fault.
  • A principal that does not exist in the organization. A user or service account of another organization is reported the same way.
  • The organization owner, who holds every action already.
  • A role the principal already holds.
  • An eleventh grant for the same principal.

Listing

GET /v2/iam/grants lists the organization’s grants, newest first, and filters by role or by principal.
GET /v2/iam/grants?filter[principal_id]={service_account_id}
filter[role_id] lists everyone who holds a role, which is what to check before deleting it.

Revocation

DELETE /v2/iam/grants/{id} revokes the grant and returns it. The principal loses the role’s statements for new requests within five seconds. Once the organization has enabled IAM, a principal whose last grant is revoked is refused every action until it holds a role again.