Role Assignment API reference

The Role Assignment API lets you manage which roles are assigned to users within your organization. A role assignment connects a user to a role within a specific scope, such as your organization or an individual account.

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

Authentication and authorization

The Role Assignment 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 these endpoints, grant your OAuth app the following permissions. Configure these permissions on your OAuth app in the Twilio Console.

Endpoint	Required permission
List role assignments	`twilio/iam/role-assignments/list`
Create a role assignment	`twilio/iam/role-assignments/create`
Delete a role assignment	`twilio/iam/role-assignments/delete`

(information)

Info

The Role Assignment API doesn't support updating an existing role assignment. To change a user's role, delete the existing role assignment and create a new one.

Bulk role assignment isn't supported. You can only create or delete one role assignment per request.

Resource properties

Property	Type	Description
`sid`	string	The unique identifier for the role assignment. Starts with `IY`.
`role_sid`	string	The SID of the assigned role. Starts with `IX`.
`scope`	string	The SID that defines where the role applies. Can be an Organization SID (`OR`), Account SID (`AC`), or Subaccount SID (`AC`).
`identity`	string	The SID of the user the role is assigned to. Starts with `US`.
`resource_type`	string or null	The resource type for resource-level role assignments.
`resource_id`	string or null	The resource ID for resource-level role assignments.

List role assignments

Retrieve a paginated list of role assignments. You can filter by user identity, scope, resource type, and resource ID.

GET /v2/Organizations/RoleAssignments

Query parameters

Parameter	Type	Necessity	Description
`Identity`	string	Optional	Filter by user SID.
`Scope`	string	Optional	Filter by scope SID.
`ResourceType`	string	Optional	Filter by resource type for resource-level role assignments.
`ResourceId`	string	Optional	Filter by resource ID for resource-level role assignments.
`PageSize`	integer	Optional	Number of results per page. Default: `50`, maximum: `100`.
`PageToken`	string	Optional	Token for fetching the next page of results.

List role assignments example

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

Response

200 OK

1{
2  "content": [
3    {
4      "sid": "IYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5      "role_sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6      "scope": "ORaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8      "resource_type": null,
9      "resource_id": null
10    },
11    {
12      "sid": "IYbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
13      "role_sid": "IXbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
14      "scope": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15      "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
16      "resource_type": null,
17      "resource_id": null
18    },
19    {
20      "sid": "IYcccccccccccccccccccccccccccccccc",
21      "role_sid": "IXcccccccccccccccccccccccccccccccc",
22      "scope": "ORaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
23      "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
24      "resource_type": "billing_group",
25      "resource_id": "billing_group_1a2b3c4d5e6f7g8h9i0j1k2l3m"
26    }
27  ],
28  "meta": {
29    "page_size": 50,
30    "page": 0,
31    "key": "content",
32    "first_page_url": "https://iam.twilio.com/v2/Organizations/RoleAssignments?PageSize=50&Page=0&Identity=USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
33    "previous_page_url": null,
34    "next_page_url": null,
35    "url": "https://iam.twilio.com/v2/Organizations/RoleAssignments?PageSize=50&Page=0&Identity=USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
36  }
37}

Create a role assignment

Assign a role to a user within a specific scope.

POST /v2/Organizations/RoleAssignments

Request body

Parameter	Type	Necessity	Description
`role_sid`	string	Required	The SID of the role to assign. Starts with `IX`.
`scope`	string	Required	The SID that defines where the role applies. Can be an Organization SID (`OR`) or Account SID (`AC`).
`identity`	string	Required	The SID of the user to assign the role to. Starts with `US`.
`resource_type`	string	Optional	The resource type for resource-level role assignments.
`resource_id`	string	Optional	The resource ID for resource-level role assignments.

Organization scope request example

1curl -X POST 'https://iam.twilio.com/v2/Organizations/RoleAssignments' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Content-Type: application/json' \
4     -d '{
5         "role_sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6         "scope": "ORaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7         "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
8     }'

Account scope request example

1curl -X POST 'https://iam.twilio.com/v2/Organizations/RoleAssignments' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Content-Type: application/json' \
4     -d '{
5         "role_sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6         "scope": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7         "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
8     }'

Resource-level request example

1curl -X POST 'https://iam.twilio.com/v2/Organizations/RoleAssignments' \
2     -H 'Authorization: Bearer {access_token}' \
3     -H 'Content-Type: application/json' \
4     -d '{
5         "role_sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6         "scope": "ORaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7         "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8         "resource_type": "billing_group",
9         "resource_id": "billing_group_1a2b3c4d5e6f7g8h9i0j1k2l3m"
10     }'

Response

201 Created

1{
2  "sid": "IYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "role_sid": "IXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "scope": "ORaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5  "identity": "USaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6  "resource_type": "billing_group",
7  "resource_id": "billing_group_1a2b3c4d5e6f7g8h9i0j1k2l3m"
8}

Error responses

400 Bad Request - Invalid parameters:

1{
2  "code": 20001,
3  "message": "Invalid request",
4  "more_info": "https://www.twilio.com/docs/errors/20001",
5  "status": 400
6}

403 Forbidden - Insufficient permissions:

1{
2  "code": 20003,
3  "message": "Authorization denied",
4  "more_info": "https://www.twilio.com/docs/errors/20003",
5  "status": 403
6}

Delete a role assignment

Remove a role assignment from a user.

DELETE /v2/Organizations/RoleAssignments/{RoleAssignmentSid}

Path parameters

Parameter	Type	Necessity	Description
`RoleAssignmentSid`	string	Required	The SID of the role assignment to delete. Starts with `IY`.

Delete a role assignment example

1curl -X DELETE 'https://iam.twilio.com/v2/Organizations/RoleAssignments/IYaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
2     -H 'Authorization: Bearer {access_token}'

Response

204 No Content - Role assignment successfully deleted.

Error responses

403 Forbidden - Insufficient permissions:

1{
2  "code": 20003,
3  "message": "Authorization denied",
4  "more_info": "https://www.twilio.com/docs/errors/20003",
5  "status": 403
6}