Product UpdatesStatus PageWorkato Academy
English
日本語
Get a trial
Developer API
Resources
Roles

Project roles ​

Use the following endpoints to manage your project roles.

Project roles can have the following values:

ValueDefinition
systemDefault roles provided by Workato.
customRoles created manually within a workspace.
inheritableCustom roles from an AHQ admin or Embedded partner workspace that are inheritable by child workspaces.
inheritedRoles inherited by a child workspace from its AHQ or Embedded parent workspace.

Rate limits ​

Project roles resource has the following rate limit:

Quick reference ​

TypeResourceDescription
GET/api/project_rolesList project roles.
GET/api/project_roles/:idGet project role details.
POST/api/project_rolesCreate a project role.
PUT/api/project_roles/:idUpdate a project role.
DELETE/api/project_roles/:idDelete a project role.

List project roles ​

Retrieves a list of project roles from a workspace.

shell
GET /api/project_roles

Query parameters ​

NameTypeDescription
namestring
optional		Filter project roles by their name.
page[number]integer
optional		The page number to retrieve. The default value is 1.
page[size]integer
optional		The number of items per page to retrieve. The default and maximum value is 100.

Sample request ​

shell
curl -X GET 'https://www.workato.com/api/project_roles?name=Builder&page[number]=1&page[size]=100' \
  -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "data": [
    {
      "id": 1,
      "name" : "Builder",
      "members_count": 1,
      "type": "custom",
      "created_at": "2024-08-02T13:35:11.691-07:00",
      "updated_at": "2024-08-02T13:35:11.691-07:00"
    }
  ],
  "total": 1,
  "page": {
    "number": 1,
    "size": 100
  }
}

Get project role details ​

Retrieves a project role by its ID.

shell
GET /api/project_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the project role to retrieve.

Sample request ​

shell
curl -X GET 'https://www.workato.com/api/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>'

Response ​

json
{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Developer",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 1,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

Create a project role ​

Creates a new project role.

shell
POST /api/project_roles

Request body ​

NameTypeDescription
project_roleobject
required		Defines the project role to create.
project_role[name]string
required		The name of the project role to create. The maximum length is 200 characters.
project_role[config]object
required		Defines the privileges assigned to the role.
project_role[inheritable]boolean
optional		Child workspaces inherit the role when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

Sample request ​

shell
curl -X POST 'https://www.workato.com/api/project_roles' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_role": { 
          "name": "Builder",
          "config": { "recipe": { "privileges": "all" } },
          "inheritable": false
        }
      }'

Response ​

json
{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Builder",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 0,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

Update a project role ​

Updates an existing project role by its ID.

shell
PUT /api/project_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the project role to update.

Request body ​

NameTypeDescription
project_roleobject
required		Defines the updated project role.
project_role[name]string
required		The updated name of the project role. The maximum length is 200 characters.
project_role[config]object
required		Defines the privileges assigned to the role.
project_role[inheritable]boolean
optional		Child workspaces inherit the role when set to true. The default value is false. This value can only be set to true in Admin AHQ or Embedded partner workspaces.

Sample request ​

shell
curl -X PUT 'https://www.workato.com/api/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "project_role": { 
          "name": "Builder",
          "config": { "recipe": { "privileges": "all" } },
          "inheritable": false
        }
      }'

Response ​

json
{
  "data": {
    "id": "pr-APmWpgTs-dwARGH",
    "name" : "Builder",
    "config": { "recipe": { "privileges": "all" } },
    "members_count": 1,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

Delete a project role ​

Deletes a project role by its ID.

shell
DELETE /api/project_roles/:id

Path parameters ​

NameTypeDescription
idstring
required		The ID of the project role to delete.

Sample request ​

shell
curl -X DELETE 'https://www.workato.com/api/project_roles/pr-APmWpgTs-dwARGH' \
  -H 'Authorization: Bearer <api_token>'

Response ​

A successful request returns a 204 No Content status code. The API deletes the project role and returns an empty response body.

400 BAD REQUEST

A 400 Bad Request error indicates that the server couldn't process the request due to client-side issues. Common causes include malformed requests, invalid fields, or violations of field constraints, such as unsupported data types.

In the following example, the request fails because the role is still assigned to some collaborators:

json
{ 
  "errors": [
    {
      "code": "bad_request",
      "title": "You can’t delete a role when collaborators are assigned to the role."
    }
  ] 
}

Last updated: