# 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 |
---|---|---|
POST | Invite 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. |
All | All other Workspace collaborators endpoints | 60 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. |
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
- Request 2: Invite a collaborator using
env_roles
: No access - Request 3: Invite a collaborator with a nonexistent or unavailable role
- Request 4: Invite a collaborator to a nonexistent environment
# 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 |
---|---|---|
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 andfederation_manager
indicates the user is a workspace moderator. - User groups
- Role
- External ID
- Name
- 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
- Request 2: Update collaborator roles in all environments
- Request 3: Update collaborator roles using a nonexistent or unavailable role
- Request 4: Update collaborator roles in a nonexistent environment
# 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