Workspot provides a REST API for Workspot Control. This API uses standard REST concepts and provides a simple command interface for performing administrative tasks.
This guide shows you how to use the API. The examples use Microsoft PowerShell, which should be readable enough that non-PowerShell users can treat them as pseudo-code when creating equivalent routines.
The API is available for Workspot installations in both the Microsoft Azure and Google GCP Clouds. The two behave identically, except that the "redeploy," "screenshotDesktop," "moveDesktop," and "cancelMoveDesktop" commands are not currently available for GCP.
The basics of making API calls are covered in preparing to use the API and Making Workspot API Calls. A PowerShell example is given in Example: Get a Workspot Usage Report.
Most commands are self-documenting, but the more complex ones are described in this article.
Accessing the Workspot Control API
The Workspot Control API is reached via https://api.workspot.com.
The preferred URLs are:
https://api.eu.workspot.com:443 for customers with Control deployments in the EU region.
https://api.us.workspot.com:443 for customers with Control deployments in the Us region.
You can also reach the Control API from the old address of https://api.workspot.com.
The API homepage is shown below:
The API is largely self-documenting. Clicking the api-controller link shows a complete list of functions and their syntax.
API commands, part 1.
API commands, part 2
Clicking an individual command gives a summary, syntax, error codes and their meaning, and the opportunity to use the command interactively, as shown for the Delete command below:
Limitations
General
You cannot take the successful completion of a command for granted and must poll its status and be prepared to resubmit it if it fails in part or in full.
Concurrent Provisioning of Desktops
Only a limited number of desktop provisioning requests can be outstanding at any given time. This is across all Clouds and pools. If the current limit is exceeded, any rejected requests will have a status message like this:
{
"status": "Failed",
"startTime": "2024-02-06T10:50:37.621Z",
"endTime": "2024-02-06T10:50:37.644Z",
"details": null,
"errorInfo": {
"error": "maxConcurrentProvisioningError",
"description": "You have reached the max concurrent provisionings allowed. Please wait for some time and try again."
}
}
In addition to this limit, no desktops are provisioned in parallel. Provisioning is always one desktop at a time.
Details About Selected Commands
Taking a Desktop Screen Shot
The API allows you to take screen captures of desktops. The snapshot is of the login screen only; it returns nothing if there’s an active desktop session.
When the screenshot is complete, the Status URL contains a link to the screen capture. This is typically used to debug boot issues, such as the desktop being unavailable because a Windows Update is being applied. The screenshot expires after 15 minutes.
Remote Assistance API Call
Remote assistance sessions can now be initiated from the Control API (in addition to from the Control UI). The parameters for the API call are:
Email address: The address Control associates with the end-user needing assistance.
desktopID: The desktop ID string of the end-user, as given by the API.
Password: A temporary password used only for this Remote Assistance session, set by the administrator.
poolID: The ID of the desktop pool containing the end-user’s desktop.
As with any Remote Assistance session, the end-user’s system will generate a .msrincident file. This will be transferred to Workspot Control by the Workspot Agent on the desktop, then uploaded to the Cloud. A link to this file is contained in the Status URL response.
The Expert role for the Remote Assistance session can be accepted by any user with access to the .msrincident file, the password, and who has a desktop with access to the same network as the end-user. In other words, once the expert has the .msrincident file and the password, a standard Remote Assistance session is the next step.
The .msrincident file expires one hour after creation, so the Remote Assistance session must be started before then.
The response format is given below.
Moving Desktops
The moveDesktop command lets you transfer a persistent desktop to a different pool while keeping it assigned to the same user. The desktop is transferred, the new desktop is powered up, and when this succeeds, the old desktop is deleted. However, a snapshot of the original is retained and can be restored by Workspot Support.
Note: This command is available only on Azure, and for persistent desktops only.
How it Works
Moving a desktop does the following:
The source desktop is shut down.
A snapshot is made of the source desktop.
A copy of the desktop is made in the target pool.
The new desktop is powered on.
The Workspot Agent registers the desktop.
The end-user's assignment is transferred to the new desktop. When the end-user launches the desktop, everything seems the same as before, including the desktop's DNS name.
The source desktop is deleted.
Best Practices When Moving Desktops
Moving desktops can be disruptive to users and can run into throttling limits with Cloud providers. Use these best practices when moving desktops:
Do not reboot or redeploy a desktop VM while migration is in progress. During migration, the desktop will be inaccessible and the end-user may try to reboot it. To minimize this problem, move desktops during off-hours, inform the users of the downtime, or both.
Limit the number of simultaneous moveDesktop calls. The number of outstanding API calls to create or move desktops should be capped at ten for your entire enterprise.
Add a delay of 60 seconds or more between moveDesktop calls.
Limitations
The moveDesktop and cancelMoveDesktop calls are available only for Azure persistent desktops.
Desktops that are suspended, are part of a regional disaster recovery event, or have a connected user cannot be moved.
Both the source and the target pools must be in the same Azure region.
The target desktop pool has to use a VM that's consistent with the source pool. For example, you cannot move a GPU workstation into a non-GPU pool. In general, the SKUs have to be the same.
Troubleshooting
Failures in the early stages of the move leave the source desktop in place, and it is still the copy assigned to the end-user. Very early failures (when powering down or backing up the source desktop) cause the source desktop to be powered back on, making it available to the user.
If the failure happens later in the process, the source desktop remains powered down. If the end-user's desktop assignment hasn't been transferred to to the target desktop, rebooting the source desktop is all that is required. Otherwise, use the cancelMoveDesktop API command to bring back the source desktop.
If for some reason the Workspot Agent takes more than a few hours to register the desktop with Workspot Control, auto-registration will fail and will have to be registered manually with the pool's Agent Token by running “C:\Program Files\Workspot Agent\reregister_poolvm.bat tokenvalue" on the desktop VM.
Preparing to Use the API
Before you can use the API, you must do the following:
Contact Workspot and request API access, which is not enabled by default.
Once API access is enabled, a “Setup > API tab” will appear in Workspot Control. This tab contains two parameters you need to access the API:
The Client ID, which uniquely identifies your organization’s API access.
The Client Secret, which validates your identity.
You can generate new API security credentials at any time, at which point any existing ones become invalid.
To access the API, you need to copy both the Client ID and the Client Secret. The Client Secret is normally hidden except for a few digits. Press the Reveal button to make the Client Secret visible.
You now have the information you need to make API calls.
Making Workspot API Calls
A Workspot REST API call is consists of a properly formatted HTTP POST, GET, or DELETE command with a base URL of https://api.us. workspot.com/ or https://api.eu. workspot.com/, which from here on we will call https://api.REGION.workspot.com.
Each API session starts with authentication, which provides an access token that is included with each subsequent request.
Scripting
A PowerShell example is shown below, using a desktop usage report as the example.
Postman is anoter popular option. See Using Postman with the Control API for more information.
Authentication
To use the API, you need to authenticate yourself. This process normally uses an OAuth 2.0 token or an Entra ID token. Entra ID tokens are mandatory on Entra-ID-only deployments.
The rest of this article assumes you are using an OAuth 2.0 token
For Entra ID authentication, see TBD.
OAuth Token Authentication
The OAuth token is generated through a call to https://api.REGION.workspot.com/oauth/token. Its parameters include the string “Client_ID:Client_Secret” that you got from Workspot Control, and a few other parameters, such as the email and password of a Control administrator. See the sample code for details.
This token remains valid until it expires an hour later, at which point you use the same procedure to generate a new one.
Once you have the OAuth token, you can use the other functions of the API.
Example: Get a Workspot Usage Report
The example below creates an OAuth token and then calls the API to retrieve a usage report for the indicated date range.
In all the examples in this document, the parameters are declared at the top, but are left blank for security reasons. For this code example, there are two sets of parameters: OAuth token parameters and usage report parameters.
The OAuth parameters are:
Client ID
Client Secret
Control User (email address of a Control admin account)
Control Password
The user report parameters are:
Start Date for the report in YYYY-MM-DD format, no more than 30 days in the past
End date for the report, as above
Optional CSV path for the output file. The report is always fetched in JSON format (the only supported option). If the CSV option is specified, the output is converted into CSV format and saved to the specified file. Otherwise, it is displayed without conversion on the PowerShell console, as shown below:
Most of these values should be self-explanatory except for the following:
costCenter is the value in the AD user record field, if any, selected to represent which accounting group the user belongs to. If the cost center feature is not enabled, this will always be blank. See Using the Cost Center Feature in Workspot Control
timeSpent is the number of hours the user spent actively signed in to desktops and apps.
Sessions are the number of times the user-initiated a new desktop or application session.
Usage Report Request Flow
This example uses Windows PowerShell. The code does the following:
After declaring variables (left blank here for security), the admin user’s credentials are converted into base64 and the API is called to get the authentication token.
This is done with an HTTP POST request to https://api.REGION.workspot.com/oauth/token.
This URL is not self-documented on https://api.REGION.workspot.com. See the code for invocation details.
Then the API is called to generate the usage report.
This is done with an HTTP POST request to https://api.REGION.workspot.com/v1.0/reports/generateusagereport.
Report generation is asynchronous, so the request returns before the report is ready, providing a status/download URL for the request. This URL is tested every five seconds with an HTTP GET until the report is ready. When the report is ready, it is provided in the body of the HTTP response.
Usage Request Code
################################################################################ Sample script to run a Workspot Usage report (for up to a thirty day window ###########################################################################################################
# Variable initialization #
$ApiClientId = "" #Workspot Control API Client ID
$ApiClientSecret = "" #Workspot Control API Client Secret
$WsControlUser = "" #Workspot Control Administrator user email address
$WsControlPass = "" #Workspot Control Administrator user password
$StartDate = "" #First date of range for report, format YYYY-MM-DD
$EndDate = "" #Last date of range for report, format YYYY-MM-DD
$CsvPath = "" #Optional path to output directly to CSV
############################
$ApiClientPair = "$($ApiClientId):$($ApiClientSecret)"
$EncodedApiCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($ApiClientPair))
$HeaderAuthValue = "Basic $EncodedApiCreds"
$Headers = @{Authorization = $HeaderAuthValue}
$PostParameters = @{username=$WsControlUser;password=$WsControlPass;grant_type='password'}
$ApiReturn = Invoke-RestMethod -Uri "https://api.workspot.com/oauth/token" -Method Post -Body $PostParameters -Headers $Headers
$ApiToken = $ApiReturn.Access_Token
$Headers = @{Authorization =("Bearer "+ $ApiToken)}$RestUri =
$ReportParams = @{
end = $EndDate
format = "JSON"
start = $StartDate
}
$ReportParamsJson = $ReportParams | ConvertTo-Json
$ReportStatusUrl = (Invoke-RestMethod -Uri "https://api.workspot.com/v1.0/reports/generateusagereport" -Method Post -Headers $Headers -Body $ReportParamsJson -ContentType 'application/json').StatusUrlDo {
Start-Sleep -Seconds 5
$StatusReturn = Invoke-RestMethod -Method GET -ContentType "application/json" -Uri
$ReportStatusUrl -Headers $Headers} Until($StatusReturn.Status -ne "InProgress")If($CsvPath) { #Output to path specified for CSV file (Invoke-RestMethod $StatusReturn.details.downloadUrl).UsersUsage | Export-CSV
$CsvPath -NoTypeInformation}
$ReportArray = (Invoke-RestMethod $StatusReturn.details.downloadUrl).UsersUsage #Write report to object in JSON format
$ReportArray #Display report to PowerShell Console