Roles

Environment roles

Use the following endpoints to manage your environment roles.

Environment 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.

LEGACY ROLE COMPATIBILITY

The following endpoints are only compatible with new roles where the role_type is environment.

Use the /api/roles endpoints instead to manage legacy roles where the role_type is privilege_group.

Rate limits

The environment roles resource has the following rate limit:

Type	Resource	Quota
All	All Environment roles endpoints	60 requests per minute

Quick reference

Type	Resource	Description
GET	/api/environment_roles	List environment roles.
GET	/api/environment_roles/:id	Get environment role details.
POST	/api/environment_roles	Create an environment role.
PUT	/api/environment_roles/:id	Update an environment role.
DELETE	/api/environment_roles/:id	Delete an environment role.

List environment roles

Retrieves a list of environment roles from your workspace.

GET https://YOUR_DATA_CENTER/api/environment_roles

Query parameters

Name	Type	Description
name	string optional	Filter environment 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://YOUR_DATA_CENTER/api/environment_roles?name=:name_value&page[number]=:page_number_value&page[size]=:page_size_value' \
  -H 'Authorization: Bearer <api_token>'

Response

json

{
  "data": [
    {
      "id": 1,
      "name" : "Developer",
      "members_count": 2,
      "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 environment role details

Retrieves an environment role by its ID.

GET https://YOUR_DATA_CENTER/api/environment_roles/:id

Path parameters

Name	Type	Description
id	string required	The ID of the environment role to retrieve.

Sample request

shell

curl -X GET 'https://YOUR_DATA_CENTER/api/environment_roles/:id' \
  -H 'Authorization: Bearer <api_token>'

Response

json

{
  "data": {
    "id": 1,
    "name" : "Developer",
    "config": { "team": { "privileges": "all" } },
    "members_count": 2,
    "type": "custom",
    "created_at": "2024-08-02T13:35:11.691-07:00",
    "updated_at": "2024-08-02T13:35:11.691-07:00"
  }
}

Create an environment role

Creates a new environment role.

POST https://YOUR_DATA_CENTER/api/environment_roles

Request body

Name	Type	Description
environment_role	object required	Defines the environment role to create.
environment_role[name]	string required	The name of the environment role to create. The maximum length is `200` characters.
environment_role[config]	object required	Defines the privileges assigned to the role.
environment_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://YOUR_DATA_CENTER/api/environment_roles' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "environment_role": {
          "name": ":name",
          "config": :config,
          "inheritable": :true_or_false
        }
      }'

Response

json

{
  "data": {
    "id": 1,
    "name" : "Developer",
    "config": { "team": { "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 an environment role

Updates an existing environment role by its ID.

PUT https://YOUR_DATA_CENTER/api/environment_roles/:id

Path parameters

Name	Type	Description
id	string required	The ID of the environment role to update.

Request body

Name	Type	Description
environment_role	object required	Defines the updated environment role.
environment_role[name]	string required	The updated name of the environment role. The maximum length is `200` characters.
environment_role[config]	object required	Defines the privileges assigned to the environment role.
environment_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://YOUR_DATA_CENTER/api/environment_roles/:id' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "environment_role": {
          "name": ":name",
          "config": :config,
          "inheritable": :true_or_false
        }
      }'

Response

json

{
  "data": {
    "id": 1,
    "name" : "Builder",
    "config": { "team": { "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"
  }
}

Delete an environment role

Deletes an environment role by its ID.

DELETE https://YOUR_DATA_CENTER/api/environment_roles/:id

Path parameters

Name	Type	Description
id	string required	The ID of the environment role to delete.

Sample request

shell

curl -X DELETE 'https://YOUR_DATA_CENTER/api/environment_roles/:id' \
  -H 'Authorization: Bearer <api_token>'

Response

A successful request returns a 204 No Content status code. The API deletes the environment 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:

Environment roles ​

Rate limits ​

Quick reference ​

List environment roles ​

Query parameters ​

Sample request ​

Response ​

Get environment role details ​

Path parameters ​

Sample request ​

Response ​

Create an environment role ​

Request body ​

Sample request ​

Response ​

Update an environment role ​

Path parameters ​

Request body ​

Sample request ​

Response ​

Delete an environment role ​

Path parameters ​

Sample request ​

Response ​

Environment roles

Rate limits

Quick reference

List environment roles

Query parameters

Sample request

Response

Get environment role details

Path parameters

Sample request

Response

Create an environment role

Request body

Sample request

Response

Update an environment role

Path parameters

Request body

Sample request

Response

Delete an environment role

Path parameters

Sample request

Response