# 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.
env_roles	object required	The environment roles object.
env_roles[environment_type]	string required	The type of environment in the workspace where you plan to invite the collaborator.
env_roles[name]	string required	The role to assign the collaborator for the specific environment.
role_name	string deprecated	This field is deprecated. Use `env_roles` instead, even for single-environment workspaces.

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

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

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

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

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 users 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.
`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",
            "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"
        }
    ],
    "total": 2
}

# 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: 10/7/2024, 5:52:47 PM

# Workspace collaborators

# Quick reference

# Invite a collaborator

# Payload

# 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

# Get list of collaborators

# Query parameters

# 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 `env_roles`

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