Role API reference

The Role API lets you retrieve the list of roles available within your organization. Roles define a set of permissions that determine what actions a user can perform. To learn more about roles, see types of roles.

Base URL: https://iam.twilio.com/v2/Organizations

Authentication and authorization

The Role API is an Organization-level API. You can only access it using OAuth credentials. Account Auth Tokens and API Keys aren't supported.

To create an OAuth app and generate an access token, follow the steps in Set up OAuth.

In subsequent requests, use the returned access_token as a Bearer token:

Authorization: Bearer {access_token}

Required OAuth app permissions

To call this endpoint, grant your OAuth app the following permission. In the Twilio Console, configure this permission on your OAuth app.

Endpoint	Required permission
List roles	`twilio/iam/role-assignments/list`

Resource properties

Property	Type	Description
`sid`	string	The unique identifier for the role. Starts with `IX`.
`friendly_name`	string	A human-readable name for the role.
`external_description`	string	A description of what the role provides access to.
`product_group`	string	The product group this role belongs to (for example, `iam`, `billing`, `messaging`).
`lowest_level`	string	The lowest scope level at which this role can be assigned. One of `ORGANIZATION`, `ACCOUNT`, or `SUB_ACCOUNT`.
`role_product_group`	object	The product group details including `product_group` and `friendly_name`.
`policy`	object	The permissions policy for this role, containing `allow` (array of permission strings), `deny` (array or null), and `format` (integer).
`resource_types`	array or null	The resource types this role can be scoped to for resource-level role assignments. Null if the role doesn't support resource-level scoping.
`date_created`	string	The date and time the role was created, in ISO 8601 format.
`date_updated`	string	The date and time the role was last updated, in ISO 8601 format.

List roles

Retrieve a paginated list of roles available in your organization.

GET /v2/Organizations/Roles

Query parameters

Parameter	Type	Necessity	Description
`Search`	string	Optional	Search by role name or SID.
`RoleProductGroup`	string	Optional	Filter by product group.
`Expand`	boolean	Optional	Expand policy details and permissions.
`ResourceTypes`	string	Optional	Filter by comma-separated resource types.
`PageSize`	integer	Optional	Number of results per page. Default: `50`, maximum: `1000`.
`PageToken`	string	Optional	Token for fetching the next page of results.

Example request

1curl -X GET 'https://iam.twilio.com/v2/Organizations/Roles' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Accept: application/json'

Response

200 OK

1{
2  "roles": [
3    {
4      "sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "friendly_name": "Example Viewer",
6      "external_description": "View-only access to example resources within the organization",
7      "product_group": "billing",
8      "lowest_level": "ORGANIZATION",
9      "role_product_group": {
10        "product_group": "billing",
11        "friendly_name": "Billing"
12      },
13      "policy": {
14        "allow": [
15          "/twilio/billing/billing-profile/read",
16          "/twilio/billing/payment-methods/list",
17          "/twilio/billing/receipts/list",
18          "/twilio/billing/invoice.statements/list"
19        ],
20        "deny": null,
21        "format": 1
22      },
23      "resource_types": null,
24      "date_created": "2025-01-15T10:30:00Z",
25      "date_updated": "2025-02-20T14:45:00Z"
26    }
27  ],
28  "meta": {
29    "page_size": 50,
30    "page": 0,
31    "key": "roles",
32    "first_page_url": "https://iam.twilio.com/v2/Organizations/Roles?PageSize=50&Page=0",
33    "previous_page_url": null,
34    "next_page_url": null,
35    "url": "https://iam.twilio.com/v2/Organizations/Roles?PageSize=50&Page=0"
36  }
37}

Filter by product group example

1curl -X GET 'https://iam.twilio.com/v2/Organizations/Roles?RoleProductGroup=billing' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Accept: application/json'

Search for roles example

1curl -X GET 'https://iam.twilio.com/v2/Organizations/Roles?Search=billing' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Accept: application/json'