Roles

Project roles

Use the following endpoints to manage project roles in an Embedded customer workspace.

Project roles can have the following values:

Value	Definition
system	Default roles provided by Workato.
custom	Roles created manually within a workspace.
inheritable	Custom roles from an AHQ admin or Embedded partner workspace that are inheritable by child workspaces.
inherited	Roles inherited by a child workspace from its AHQ or Embedded parent workspace.

Rate limits

The project roles resource has the following rate limit:

Quick reference

Type	Resource	Description
GET	/api/managed_users/:managed_user_id/project_roles	List project roles in a customer workspace.
GET	/api/managed_users/:managed_user_id/project_roles/:id	Get a project role from a customer workspace.
POST	/api/managed_users/:managed_user_id/project_roles	Create a project role in a customer workspace.
PUT	/api/managed_users/:managed_user_id/project_roles/:id	Update a project role in a customer workspace.
DELETE	/api/managed_users/:managed_user_id/project_roles/:id	Delete a project role from a customer workspace.

List project roles in a customer workspace

Retrieves a list of project roles from an Embedded customer workspace.

shell

GET /api/managed_users/:managed_user_id/project_roles

Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.

Query parameters

Name	Type	Description
name	string 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/managed_users/19029/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 a project role from a customer workspace

Retrieves a project role from an Embedded customer workspace.

shell

GET /api/managed_users/:managed_user_id/project_roles/:id

Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project role to retrieve.

Sample request

shell

curl -X GET 'https://www.workato.com/api/managed_users/19029/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 in a customer workspace

Creates a new project role in an Embedded customer workspace.

shell

POST /api/managed_users/:managed_user_id/project_roles

Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.

Request body

Name	Type	Description
project_role	object 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 for 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/managed_users/19029/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 in a customer workspace

Updates an existing project role in an Embedded customer workspace.

shell

PUT /api/managed_users/:managed_user_id/project_roles/:id

Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project role to update.

Request body

Name	Type	Description
project_role	object required	Defines the updated project role.
project_role[name]	string required	The updated project role name. The maximum length is `200` characters.
project_role[config]	object required	Defines the updated privileges for the project 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/managed_users/19029/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 from a customer workspace

Deletes a project role from an Embedded customer workspace.

shell

DELETE /api/managed_users/:managed_user_id/project_roles/:id

Path parameters

Name	Type	Description
managed_user_id	string required	The Embedded customer ID or external ID. External IDs must be URL encoded and prefixed with an `E`, for example: `EA2300`.
id	string required	The ID of the project role to delete.

Sample request

shell

curl -X DELETE 'https://www.workato.com/api/managed_users/19029/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 collaborators:

json

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

Last updated:

Project roles ​

Rate limits ​

Quick reference ​

List project roles in a customer workspace ​

Path parameters ​

Query parameters ​

Sample request ​

Response ​

Get a project role from a customer workspace ​

Path parameters ​

Sample request ​

Response ​

Create a project role in a customer workspace ​

Path parameters ​

Request body ​

Sample request ​

Response ​

Update a project role in a customer workspace ​

Path parameters ​

Request body ​

Sample request ​

Response ​

Delete a project role from a customer workspace ​

Path parameters ​

Sample request ​

Response ​

Project roles

Rate limits

Quick reference

List project roles in a customer workspace

Path parameters

Query parameters

Sample request

Response

Get a project role from a customer workspace

Path parameters

Sample request

Response

Create a project role in a customer workspace

Path parameters

Request body

Sample request

Response

Update a project role in a customer workspace

Path parameters

Request body

Sample request

Response

Delete a project role from a customer workspace

Path parameters

Sample request

Response