# Legacy roles
LEGACY ROLES
This page describes the legacy permissions model. Workato is replacing legacy roles with the new permissions model, which uses environment roles and project roles. You can migrate legacy roles using the Role migration API or the in-app migration wizard. Refer to the New permissions model documentation for more information.
Use the following endpoints to programmatically manage legacy roles.
# Rate limits
The legacy roles resource has the following rate limit:
Type | Resource | Limit |
---|---|---|
All | All Legacy roles endpoints | 60 requests per minute |
# Quick reference
Type | Resource | Description |
---|---|---|
GET | /api/roles | List custom roles. |
PUT | /api/roles/:role_id | Updates a custom role's project privileges. |
POST | /api/roles/:role_id/copy | Makes a copy of a custom role. |
# List custom roles
Lists all custom roles.
GET /api/roles
# Query parameters
Name | Type | Description |
---|---|---|
per_page | integer optional | The number of custom roles to retrieve. |
page | integer optional | The page number. If the total number of custom roles exceed the page limit, subsequent records can be retrieved by calling the next page. |
# Sample request
curl -X GET https://www.workato.com/api/roles \
-H 'Authorization: Bearer <api_token>'
# Response
[
{
"id": 478,
"name": "Developer role",
"inheritable": false,
"folder_ids": [],
"created_at": "2020-05-20T11:54:31.706-07:00",
"updated_at": "2020-05-20T11:54:31.706-07:00",
"privileges": {
"Recipes": [ ... ],
"Folders": [ ... ],
...
}
},
{
"id": 446,
"name": "Non-developer role",
"inheritable": false,
"folder_ids": [],
"created_at": "2020-04-12T08:40:11.240-07:00",
"updated_at": "2020-04-12T08:40:11.240-07:00",
"privileges": {
"Recipes": [ ... ],
"Folders": [ ... ],
...
}
}
]
# Update a custom role
Updates the projects accessible to a custom collaborator role. You can set the privilege to all projects or specific projects by their folder IDs. The folder IDs can be obtained with the GET folders API endpoint.
PUT /api/roles/:id
# Path parameters
Name | Type | Description |
---|---|---|
id | integer required | The ID of the custom role. |
# Request body
Name | Type | Description |
---|---|---|
all_folders | string required | Either "true" or "false". Must be "false" if "folder_ids" is specified. |
folder_ids | array | Array of project IDs. |
# Sample request
curl -X PUT https://www.workato.com/api/roles/490 \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"all_folders": "false",
"folder_ids": [1232, 1224]
}'
# Response
{
"id": 45899,
"name": "Marketing Recipe Operator",
"inheritable": false,
"folder_ids": [
1232,
1224
],
"created_at": "2022-12-26T02:26:04.582-08:00",
"updated_at": "2022-12-26T02:37:04.124-08:00",
"privileges": {
"Recipes": [
"read",
"create",
"update",
"run",
"read_run_history"
]
}
}
# Copy a custom role
Creates a copy of a custom collaborator role with the ability to change the folders accessible by the role. The folder IDs can be obtained with the GET folders API endpoint.
POST /api/roles/:id/copy
# Path parameters
Name | Type | Description |
---|---|---|
id | integer required | The ID of the custom role. |
# Request body
Name | Type | Description |
---|---|---|
name | string required | Name of the custom role. |
folder_ids | array | Array of project IDs. |
# Sample request
curl -X POST https://www.workato.com/api/roles/490/copy \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Finance team developer",
"folder_ids": ["1232", "1224"]
}'
# Response
{
"id": 546,
"name": "Finance team developer",
"inheritable": false,
"folder_ids": ["1232", "1224"],
"created_at": "2020-08-14T07:23:19.599-07:00",
"updated_at": "2020-08-14T07:23:19.599-07:00"
}
Last updated: 10/7/2025, 6:01:50 PM