Roles

The Roles APIs allow users to programmatically manage custom roles for their teams.

Quick reference

Type	Resource	Description
GET	/api/roles	List custom roles.
PUT	/api/roles/:role_id	Updates a custom role's project privilege
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

Payload

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

Payload

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"
}