# Workspace collaborators

Use the following endpoints to manage collaborators in your workspace.

API CLIENT ACCESS

API clients require access to the DEV environment to manage collaborators. Refer to Create a client role to configure an API client's access.

# Rate limits

Workspace collaborator resources have the following rate limits:

Type Resource Limit
POSTInvite a collaborator:
/api/member_invitations
60 requests per minute
Additionally, you can send one request per user and workspace ID every 20 minutes to this endpoint.
AllAll other Workspace collaborators endpoints60 requests per minute

# Quick reference

Type Resource Description
POST /api/member_invitations Invite a collaborator to a workspace.
GET /api/members Get list of collaborators.
GET /api/members/:id Get collaborator details.
PUT /api/members/:id Update collaborator roles.
DELETE /api/members/:id Delete a collaborator.
GET /api/members/:id/project_grants List a workspace's project grants.
GET /api/members/:id/privileges Get collaborator privileges.
GET /api/members/:id/projects_privileges Get collaborator project privileges.

# Invite a collaborator

Invite a collaborator to your workspace. The API sends an email invitation if the email you provide doesn't belong to an existing user. Collaborators can join the workspace after they create a Workato account. You can invite a specific email and workspace combination once every twenty minutes.

POST /api/member_invitations

# Request body

Name Type Description
name string
required
The name of the collaborator.
email string
required
The email of the collaborator.
env_roles object
required
Defines the collaborator's environment roles.
env_roles[environment_type] string
required
The type of environment in the workspace where you plan to invite the collaborator. Use dev for single-environment workspaces.
env_roles[name] string
required
The role to assign the collaborator for the specific environment.
env_roles[role_type] string
optional
The type of role to assign the collaborator. Accepted values include privilege_group and environment. The default value is privilege_group.
role_name string
deprecated
This field is deprecated. Use env_roles instead, even for single-environment workspaces.
user_group_ids array of strings
optional
The IDs of collaborator groups to assign.

# Sample requests

# Request 1: Invite a collaborator using env_roles

This example request creates an invitation for the dev, test, and prod environments. It assigns the collaborator an Admin role in the dev environment, an Analyst role in the test environment, and an Operator role in the prod environment.

curl -X POST 'https://www.workato.com/api/member_invitations' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Josh",
        "email": "[email protected]",
        "user_group_ids": [
          "am-WxEKCibh-dTXBtz", 
          "am-APNHJbmM-hfhTD8"
        ],
        "env_roles": [
          { 
            "environment_type": "dev", 
            "name": "Admin", 
            "role_type": "privilege_group" 
          },
          { 
            "environment_type": "test", 
            "name": "Admin", 
            "role_type": "privilege_group" 
          },
          { 
            "environment_type": "prod", 
            "name": "Admin", 
            "role_type": "privilege_group" 
          }
        ]
      }'
Response 1: Invite a collaborator using env_roles
{
    "result": "ok"
}

# Request 2: Invite a collaborator using env_roles - No access

This example creates an invitation solely for the prod environment. By omitting additional environments and roles from the env_roles object, the default behavior assigns the collaborator a No access role in all other environments.

curl -X POST 'https://www.workato.com/api/member_invitations' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Josh",
        "email": "[email protected]",
        "user_group_ids": [
          "am-WxEKCibh-dTXBtz", 
          "am-APNHJbmM-hfhTD8"
        ],
        "env_roles": [
          { 
            "environment_type": "prod", 
            "name": "Operator", 
            "role_type": "privilege_group" 
          }
        ]
      }'
Response 2: Invite a collaborator using env_roles - No access
{
    "result": "ok"
}

# Request 3: Invite a collaborator with a nonexistent or unavailable role

When you invite a collaborator using a role that doesn't exist or isn't available, this endpoint returns a 400 error: Role Not existing role not found.

curl -X POST 'https://www.workato.com/api/member_invitations' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Josh",
        "email": "[email protected]",
        "user_group_ids": [
          "am-WxEKCibh-dTXBtz", 
          "am-APNHJbmM-hfhTD8"
        ],
        "env_roles": [
          { 
            "environment_type": "prod", 
            "name": "Not existing role", 
            "role_type": "privilege_group" 
          }
        ]
      }'
Response 3: Invite a collaborator with a nonexistent or unavailable role
{
    "message": "Role Not existing role not found"
}

# Request 4: Invite a collaborator to a nonexistent environment

When you invite a collaborator to an environment that doesn't exist, this endpoint returns a 400 error: Environment Not existing environment not found.

curl -X POST 'https://www.workato.com/api/member_invitations' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "Josh",
        "email": "[email protected]",
        "user_group_ids": [
          "am-WxEKCibh-dTXBtz", 
          "am-APNHJbmM-hfhTD8"
        ],
        "env_roles": [
          { 
            "environment_type": "Not existing environment", 
            "name": "Operator", 
            "role_type": "privilege_group" 
          }
        ]
      }'
Response 4: Invite a collaborator to a nonexistent environment
{
    "message": "Environment Not existing environment not found"
}

# Get list of collaborators

Retrieve a list of all collaborators in a workspace. The response includes two primary elements:

Element Description
data An array of objects, each representing a collaborator.
total The total number of collaborators returned.

Each collaborator object in the data array includes the following information:

Field Description
id The user's unique identifier.
grant_type The user's grant type. This is team for workspace collaborators and federation_manager for workspace moderators.
user_groups An array of user groups assigned to the user.

| roles | An array of system or custom roles assigned to the user in different environments. | | last_activity_log | The user's latest activity in a workspace. For AHQ-enabled workspaces, it only displays the most recent action in the DEV environment. Includes activities such as sign-ins, token generation, and more. Refer to the activity audit log reference for a full list of captured events. | | external_id | The user's external ID. | | name | The user's name. | | email | The user's email for signing in to Workato. | | time_zone | The user's timezone. | | created_at | The datetime when the user was created in Workato. |

ENDPOINT ACCESS

Your API client role must be assigned the Get collaborators GET /api/members privilege to use this endpoint.

GET /api/members 

# Query parameters

Name Type Description
email string
optional
Filters the list to collaborators whose email contains the provided value. Special characters must be URL-encoded.

# Sample request

curl  -X GET 'https://www.workato.com/api/members?email=example.com' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "id": 12345,
      "grant_type": "federation_manager",
      "user_groups": [
        {
          "id": "am-WxEKCibh-dTXBtz",
          "name": "All collaborators",
          "system": true
        },
        {
          "id": "am-WxEKCibh-dTXBtg",
          "name": "Developers",
          "system": false
        }
      ],
      "roles": [
        {
          "environment_type": "dev",
          "role_name": "Admin",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "test",
          "role_name": "Admin",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "prod",
          "role_name": "Admin",
          "role_type": "privilege_group"
        }
      ],
      "last_activity_log": {
        "id": 2807129,
        "event_type": "user_login",
        "created_at": "2024-03-07T16:38:18.414-08:00"
      },
      "external_id": null,
      "name": "Rosario",
      "email": "[email protected]",
      "time_zone": "Pacific Time (US & Canada)",
      "created_at": "2021-12-14T13:01:15.935-08:00"
    },
    {
      "id": 23456,
      "grant_type": "team",
      "user_groups": [
        {
          "id": "am-WxEKCibh-dTXBtz",
          "name": "All collaborators",
          "system": true
        },
        {
          "id": "am-WxEKCibh-dTXBtg",
          "name": "Developers",
          "system": false
        }
      ],
      "roles": [
        {
          "environment_type": "dev",
          "role_name": "IT_Developer",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "test",
          "role_name": "No access",
          "role_type": "privilege_group"
        },
        {
          "environment_type": "prod",
          "role_name": "No access",
          "role_type": "privilege_group"
        }
      ],
      "last_activity_log": {
        "id": 2807129,
        "event_type": "user_login",
        "created_at": "2024-03-07T16:38:18.414-08:00"
      },
      "external_id": null,
      "name": "Noam",
      "email": "[email protected]",
      "time_zone": "Pacific Time (US & Canada)",
      "created_at": "2021-1-12T13:01:15.935-08:00"
    }
  ],
  "total": 2
}

# Get collaborator details

Get details about a collaborator you specify. This resource returns the following information in the response:

  • User ID
  • Grant type: Where team indicates the user is a workspace collaborator and federation_manager indicates the user is a workspace moderator.
  • User groups
  • Role
  • External ID
  • Name
  • Email
  • Timezone
  • Last activity log: This displays the user's most recent action within a workspace and captures the same data as the activity audit log. For workspaces with AHQ, this only displays the last activity within the DEV environment. It can include events such as logging in, logging out, joining a workspace, generating a token, disconnecting a connection, and more. Refer to our activity audit log reference documentation for a complete list of activities that are captured in the log and can be returned in this request.
  • Created at
GET /api/members/:id 

# Path parameters

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

# Sample request

curl  -X GET 'https://www.workato.com/api/members/34567' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": {
    "id": 34567,
    "grant_type": "team",
    "user_groups": [
      {
        "id": "am-WxEKCibh-dTXBtz",
        "name": "All collaborators",
        "system": true
      },
      {
        "id": "am-WxEKCibh-dTXBtg",
        "name": "Developers",
        "system": false
      }
    ],
    "roles": [
      {
        "environment_type": "dev",
        "role_name": "HR_Developer",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "test",
        "role_name": "HR_Viewer",
        "role_type": "privilege_group"
      },
      {
        "environment_type": "prod",
        "role_name": "Operator",
        "role_type": "privilege_group"
      }
    ],
    "last_activity_log": {
      "id": 2807147,
      "event_type": "user_login",
      "created_at": "2024-03-07T16:44:39.318-08:00"
    },
    "external_id": null,
    "name": "Dana",
    "email": "[email protected]",
    "time_zone": "Pacific Time (US & Canada)",
    "created_at": "2019-09-09T00:45:17.019-07:00"
  }
}

# Update collaborator roles

Updates an existing collaborator's roles by their ID. To remove a collaborator's access, include NoAccess in the request body.

PUT /api/members/:id

# Path parameters

Name Type Description
id string
required
The ID of the collaborator whose roles you plan to update.

# Request body

Name Type Description
env_roles object
required
Defines the collaborator's updated environment roles.
env_roles[environment_type] string
required
The type of workspace environment where you plan to update the collaborator's roles. Use dev for single-environment workspaces.
env_roles[name] string
required
The role to assign the collaborator for the specific environment.
env_roles[role_type] string
optional
The type of role to assign the collaborator. Accepted values include privilege_group and environment. The default value is privilege_group.

# Sample requests

# Request 1: Update collaborator roles in one environment

This example request updates the collaborator's role to Operator in the prod environment. Roles in other environments are not affected.

curl -X PUT 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "env_roles": [
          {
            "environment_type": "prod",
            "name": "Operator",
            "role_type": "privilege_group"
          }
        ]
      }'
Response 1: Update collaborator roles in one environment
{
    "data": {
        "result": "ok"
    }
}

# Request 2: Update collaborator roles in all environments

This example request updates the collaborator's role to Operator in the prod environment, Admin in the dev environment, and removes the collaborator's access to the test environment.

curl -X PUT 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "env_roles": [
          {
            "environment_type": "prod",
            "name": "Operator",
            "role_type": "privilege_group"
          },
          {
            "environment_type": "dev",
            "name": "Admin",
            "role_type": "privilege_group"
          },
          {
            "environment_type": "test",
            "name": "NoAccess",
            "role_type": "privilege_group"
          }
        ]
      }'
Response 2: Update collaborator roles in all environments
{
    "data": {
        "result": "ok"
    }
}

# Request 3: Update collaborator roles using a nonexistent or unavailable role

When you update a collaborator's role to one that doesn't exist or isn't available, this endpoint returns a 400 error: Role Custom Role not found.

curl -X PUT 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "env_roles": [
          {
            "environment_type": "prod",
            "name": "Custom Role",
            "role_type": "privilege_group"
          }
        ]
      }'
Response 3: Update collaborator roles using a nonexistent or unavailable role
{
    "errors": [
        {
            "code": 400,
            "title": "Role Custom Role not found"
        }
    ]
}

# Request 4: Update collaborator roles in a nonexistent environment

When you update a collaborator's role in an environment that doesn't exist, this endpoint returns a 400 error: Environment Custom Environment not found.

curl -X PUT 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "env_roles": [
          {
            "environment_type": "Custom Environment",
            "name": "Admin",
            "role_type": "privilege_group"
          }
        ]
      }'
Response 4: Update collaborator roles in a nonexistent environment
{
    "errors": [
        {
            "code": 400,
            "title": "Environment Custom Environment not found"
        }
    ]
}

# Delete a collaborator

Deletes a collaborator by their ID.

DELETE /api/members/:id

# Path parameters

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

# Sample request

curl -X DELETE 'https://www.workato.com/api/members/34567' \
  -H 'Authorization: Bearer <api_token>'

# Response

A successful request returns a 204 No Content status code. The collaborator is deleted, and the response body is empty.

# List a workspace's project grants

Retrieves all project grants for a workspace. This doesn't include project access granted through collaborator groups.

PROJECT GRANTS

A project grant assigns a project role to a collaborator or group. Refer to Project grants to manage project grants using the developer API or Manage project access and roles to manage project roles in the UI.

GET /api/members/:id/project_grants

# Path parameters

Name Type Description
id string
required
The ID of the workspace to retrieve project grants from.

# Query parameters

Name Type Description
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

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

# Response

{
  "data": [
    { 
      "id": "pg-AQAEnmMX-b4rPeT", 
      "project": {
        "id": 178230, 
        "name": "Development",
        "environment": {
          "id": 148425, 
          "type": "dev"
        }, 
      }, 
      "project_role": { 
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }
    }, 
    {
      "id": "pg-AQAEnmKE-xpCFwT", 
      "project": {
        "id": 178230, 
        "name": "Sales",
        "environment": {
          "id": 148426, 
          "type": "prod"
        }, 
      }, 
      "project_role": {
        "id": "pr-AQAEnmK3-EQpeYM", 
        "name": "Developers"
      }
    }
  ],
  "total": 2,
  "page": {
    "number": 1,
    "size": 100
  }
}

# Get collaborator privileges

Retrieves the privileges and roles of a collaborator by their ID. The response returns an array of roles for each environment (for example, dev, test, and prod) with the following information:

  • Environment type
  • User role
  • All permissions assigned to the role
  • Role type

The response includes roles from both the legacy model (role_type: privilege_group) and the new model (role_type: environment).

GET /api/members/:id/privileges 

# Path parameters

Name Type Description
id string
required
The ID of the collaborator whose privileges you plan to retrieve.

# Sample request

curl  -X GET 'https://www.workato.com/api/members/34567/privileges' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
    "data": [
        {
            "environment_type": "dev",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        },
        {
            "environment_type": "test",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        },
        {
            "environment_type": "prod",
            "name": "Operator",
            "role_type": "privilege_group",
            "privileges": {
                "Recipes": [
                    "read",
                    "run",
                    "read_run_history"
                ],
                "Folders": [
                    "read"
                ],
                "Projects": [
                    "read"
                ],
                "Use in recipes": [
                    "all"
                ],
                "Test automation": [
                    "read"
                ]
            }
        }
    ]
}

# Get collaborator project privileges

Retrieves project-level access for a collaborator. This includes access assigned directly or through membership in a collaborator group. You can use this endpoint to audit project permissions.

GET /api/members/:id/projects_privileges

# Path parameters

Name Type Description
id string
required
The ID of the collaborator whose project privileges you plan to retrieve.

# Sample request

curl  -X GET 'https://www.workato.com/api/members/34567/projects_privileges' \
      -H 'Authorization: Bearer <api_token>'

# Response

{
  "data": [
    {
      "environment": {
        "id": 123456,
        "type": "dev"
      },
      "projects": {
        "61722": {
          "Folders": ["create", "view"]
        }
      }
    },
    {
      "environment": {
        "id": 789123,
        "type": "prod"
      },
      "projects": {
        "74137": {
          "Folders": ["view"]
        }
      }
    }
  ]
}


Last updated: 9/9/2025, 9:19:51 PM