# 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.
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 'x-user-email: <email>' \
      -H 'x-user-token: <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": [ ... ],
            ...
        }
    }
]

# Copy a custom role

Creates a copy of a custom 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 folder IDs.

# Sample request

curl  -X POST https://www.workato.com/api/roles/490/copy \
      -H 'x-user-email: <email>' \
      -H 'x-user-token: <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"
}