# Workspace collaborators

Use the following endpoints to manage collaborators in your workspace.

ENDPOINT ACCESS

Your API client must be assigned specific privileges for the following endpoints:

Invite a collaborator
Get list of collaborators
Get collaborator details
Update collaborator roles
Get collaborator privileges

These privileges are determined by your API client role.

Additionally, if your workspace uses environments, these privileges are only available to API clients with DEV access.

To enable endpoint access:

You can enable access to these endpoints by editing an existing API client role or by creating a new API client role:

Navigate to Workspace admin > API clients > Client roles.

Select the role you plan to edit.

Alternatively, click + Add client role to create a new API client role.

Select Admin and navigate to Workspace collaborators > Collaborators.

Select the checkboxes next to the endpoints you plan to enable for this role.

Invite POST /api/member_invitations
Get collaborators GET /api/members
Get collaborator GET /api/members/:id
Update collaborator's roles PUT /api/members/:id
Get collaborator privileges GET /api/members/:id/privileges

Select the endpoints you plan to enable

# Quick reference

Type	Resource	Description
POST	/api/member_invitations	Invite a collaborator to your workspace.
GET	/api/members	Get a list of members in your workspace.
GET	/api/members/:id	Get details about a user you specify.
PUT	/api/members/:id	Update a collaborator's roles.
GET	/api/members/:id/privileges	Get the role and privileges for a workspace user you specify.

# Invite a collaborator

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

ENDPOINT ACCESS

Your API client role must be assigned the Invite POST /api/member_invitations privilege to use this endpoint.

POST /api/member_invitations

# Payload

Name	Type	Description
name	string required	The name of the collaborator.
email	string required	The email of the collaborator.
role_name	string conditional	The role to assign the collaborator. Required if `env_roles` is not provided.
env_roles	object conditional	The environment roles object. Required if `role_name` is not provided.
env_roles[environment_type]	string conditional	The environment type of the workspace you're inviting the collaborator to. Required if `role_name` is not provided.
env_roles[name]	string conditional	The role to assign the collaborator for the specific environment. Required if `role_name` is not provided.

SPECIFY ROLES FOR DIFFERENT ENVIRONMENTS

You must provide either role_name or env_roles in the payload. role_name only assigns a role in the dev environment. Use env_roles to specify the environment type and role for other environments.

Workato does not support a mixed approach to assigning roles. This means that when you combine the env_roles and role_name in the payload, Workato ignores the role_name and only assigns the roles specified by the env_roles object.

# Sample requests

# Request 1: Invite a collaborator using `role_name`

This example request creates an invitation for the dev environment only.

curl  -X POST https://www.workato.com/api/member_invitations \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "name": "John",
            "email": "[email protected]",
            "role_name": "Admin"
          }'

Response 1: Invite a collaborator using role_name

{
    "result": "ok"
}

# Request 2: 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": "John",
            "email": "[email protected]",
            "env_roles": [
                  { "environment_type": "dev", "name": "Admin" },
                  { "environment_type": "test", "name": "Analyst" },
                  { "environment_type": "prod", "name": "Operator" }
            ]
          }'

Response 2: Invite a collaborator using env_roles

{
    "result": "ok"
}

# Request 3: 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": "John",
            "email": "[email protected]",
            "env_roles": [
                  { "environment_type": "prod", "name": "Operator" }
            ]
          }'

Response 3: Invite a collaborator using env_roles - No access

{
    "result": "ok"
}

# Request 4: 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": "John",
            "email": "[email protected]",
            "env_roles": [
                  { "environment_type": "prod", "name": "Not existing role" }
            ]
          }'

Response 4: Invite a collaborator with a nonexistent or unavailable role

{
    "message": "Role Not existing role not found"
}

# Request 5: 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": "John",
            "email": "[email protected]",
            "env_roles": [
                  { "environment_type": "Not existing environment", "name": "Admin" }
            ]
          }'

Response 5: Invite a collaborator to a nonexistent environment

{
    "message": "Environment Not existing environment not found"
}

# Get list of collaborators

Get a list of all users in a workspace. This resource returns the following information for each user in your workspace:

User ID
Grant type: Where team indicates the user is a workspace collaborator and federation_manager indicates the user is a workspace moderator.
Role
External ID
Name
Email
Timezone
Last activity log: This log displays the user's most recent action within a workspace. For AHQ-enabled workspaces, it only displays the latest activity in the DEV environment. The log records 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

ENDPOINT ACCESS

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

GET /api/members

# Sample request

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

# Response

{
    "data": [
        {
            "id": 12345,
            "grant_type": "federation_manager",
            "roles": [
                {
                    "environment_type": "dev",
                    "role_name": "Admin"
                },
                {
                    "environment_type": "test",
                    "role_name": "Admin"
                },
                {
                    "environment_type": "prod",
                    "role_name": "Admin"
                }
            ],
            "last_activity_log": {
                "id": 2807129,
                "event_type": "user_login",
                "created_at": "2024-03-07T16:38:18.414-08:00"
            },
            "external_id": null,
            "name": "Stefano",
            "email": "[email protected]",
            "time_zone": "Pacific Time (US & Canada)",
            "created_at": ""2021-12-14T13:01:15.935-08:00""
        },
        {
            "id": 23456,
            "grant_type": "team",
            "roles": [
                {
                    "environment_type": "dev",
                    "role_name": "IT_Developer"
                },
                {
                    "environment_type": "test",
                    "role_name": "No access"
                },
                {
                    "environment_type": "prod",
                    "role_name": "No access"
                }
            ],
            "last_activity_log": {
                "id": 2807129,
                "event_type": "user_login",
                "created_at": "2024-03-07T16:38:18.414-08:00"
            },
            "external_id": null,
            "name": "Nikhil",
            "email": "[email protected]",
            "time_zone": "Pacific Time (US & Canada)",
            "created_at": ""2021-1-12T13:01:15.935-08:00""
        }
    ]
}

# Get collaborator details

Get details about a workspace member 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.
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

ENDPOINT ACCESS

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

GET /api/members/:id

# URL parameters

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

# Sample request

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

# Response

{
    "data": {
        "id": 34567,
        "grant_type": "team",
        "roles": [
            {
                "environment_type": "dev",
                "role_name": "HR_Developer"
            },
            {
                "environment_type": "test",
                "role_name": "HR_Viewer"
            },
            {
                "environment_type": "prod",
                "role_name": "Operator"
            },
        ],
        "last_activity_log": {
            "id": 2807147,
            "event_type": "user_login",
            "created_at": "2024-03-07T16:44:39.318-08:00"
        },
        "external_id": null,
        "name": "Emily",
        "email": "[email protected]",
        "time_zone": "Pacific Time (US & Canada)",
        "created_at": "2019-09-09T00:45:17.019-07:00"
    }
}

# Update collaborator roles

Update the roles of a specified collaborator. You can assign system roles (such as Admin, Analyst, and Operator) or custom roles. To remove a collaborator's access to an environment, include NoAccess in the request payload.

PUT /api/members/:id

# URL parameters

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

# Payload

Name	Type	Description
env_roles	object required	The environment roles object.
env_roles[environment_type]	string required	The type of workspace environment where you plan to update the collaborator's roles.
env_roles[name]	string required	The role to assign the collaborator for the specific environment.

WORKSPACES WITHOUT ENVIRONMENTS ENABLED

For workspaces that do not have environments enabled, use dev as the environment_type.

# 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/:id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "env_roles": [
                { "environment_type": "prod", "name": "Operator" }
            ]
          }'

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/:id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "env_roles": [
                { "environment_type": "prod", "name": "Operator" },
                { "environment_type": "dev", "name": "Admin" },
                { "environment_type": "test", "name": "NoAccess" }
            ]
          }'

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/:id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "env_roles": [
                { "environment_type": "prod", "name": "Custom Role" }
            ]
          }'

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/:id \
      -H 'Authorization: Bearer <api_token>' \
      -H 'Content-Type: application/json' \
      -d '{
            "env_roles": [
                { "environment_type": "Custom Environment", "name": "Admin" }
            ]
          }'

Response 4: Update collaborator roles in a nonexistent environment

{
    "errors": [
        {
            "code": 400,
            "title": "Environment Custom Environment not found"
        }
    ]
}

# Get collaborator privileges

Get the role and privileges for a user you specify. This resource includes details for system and custom roles. This resource returns an array of roles for each environment in the workspace (for example, DEV, TEST, and PROD), which includes the following information:

Environment type
User role
All permissions assigned to the role

ENDPOINT ACCESS

Your API client role must be assigned the Get collaborator privileges GET /api/members/:id privilege to use this endpoint.

GET /api/members/:id/privileges

# URL parameters

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

# Sample request

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

# Response

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

Last updated: 7/18/2024, 8:15:13 PM

# Workspace collaborators

# Quick reference

# Invite a collaborator

# Payload

# Sample requests

# Request 1: Invite a collaborator using role_name

# Request 2: Invite a collaborator using env_roles

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

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

# Request 5: Invite a collaborator to a nonexistent environment

# Get list of collaborators

# Sample request

# Response

# Get collaborator details

# URL parameters

# Sample request

# Response

# Update collaborator roles

# URL parameters

# Payload

# 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

# Get collaborator privileges

# URL parameters

# Sample request

# Response

# Request 1: Invite a collaborator using `role_name`

# Request 2: Invite a collaborator using `env_roles`

# Request 3: Invite a collaborator using `env_roles` - No access