Unified Workspace API

Getting Started

April 29, 2024

Contributed by:

API usage pattern

At a high level, the client accesses the Unified Workspace API by performing calls in the following order:

Fetch the discovery configuration, to determine behavior and discover URLs for subsequent operations.
Perform authentication, to allow access to resources.
List sessions, to perform auto session re-connect at logon.
Perform session reconnect to launch any resources that the user might want to re-connect to.
Resource enumeration, to fetch (per-resource) URLs for launch, favorite, icon and operations.
Launch and favorite resources in response to user actions in the UI.
Client logs off or disconnects from desktop/application sessions and terminates the authenticated session.

Notes:

An application ID is required to make API requests to the Unified Workspace API. In order to obtain one you will need to create an OAuth client.

Requests must contain either the Citrix-ApplicationId header, or the ApplicationId query parameter with the value set to the above mentioned application ID.

Hypermedia Control and Parameterized URLs

This API uses the concept of hypermedia controls, where links to resources and actions are obtained from the server by calling the discovery API. This means that at no time should clients construct URLs (apart from the initial discovery URL). In this document various parameterized URLs are discussed, such as /resources/{id}.

It is important to note that these are indicative only, and again, the client code should not construct URLs directly. Instead, all parameterized URLs should be obtained from the API itself. For example, the URL for a particular resource action such as launch, should be extracted from the JSON response returned from the request to /resources. In that case, the launchUrl property would contain the value to use.

In some cases (indicated in the relevant sections), additional parameters can be supplied to a service that is invoked using a HTTP GET request. These parameters are supplied to the service by adding query string parameters to the base endpoint. As stated before, clients should not construct the base endpoint URL themselves. Query string parameters may already be present in the base endpoint - clients should check whether they need to provide the entire query string section, or only add parameters to the existing section.

HTTP POST Parameters

Throughout the API, any request parameters in the POST body must follow standard form URL-encoding rules, with Content-Type set to: application/x-www-form-urlencoded.

Fetch the Discovery Configuration

The first step is to call the Discovery API. This returns a JSON document describing various client configuration settings, including a number of URL paths (relative to the customer) that the client must use for subsequent API calls. For example (replace ‘customer.cloud.com’ with your customer Workspace URL):

curl https://customer.cloud.com/api/discovery/configurations --header "Citrix-ApplicationId: {APPLICATION_ID}"
<!--NeedCopy-->

Response:

{
    "services": [
        {
            "service": "store",
            "endpoints": [
                {
                    "id": "CasTicket",
                    "url": "https://customer.cloud.com/api/store/cas/tickets",
                    "capability": [
                        "CasTicket"
                    ]
                },
                {
                    "id": "CreateDetectionTicket",
                    "url": "https://customer.cloud.com/api/store/client/detection/tickets",
                    "capability": [
                        "CreateDetectionTicket"
                    ]
                },
                {
                    "id": "GetDetectionStatus",
                    "url": "https://customer.cloud.com/api/store/client/detection/status",
                    "capability": [
                        "GetDetectionStatus"
                    ]
                },
                {
                    "id": "PostClientProperties",
                    "url": "https://customer.cloud.com/api/store/client/detection/properties",
                    "capability": [
                        "PostClientProperties"
                    ]
                },
                {
                    "id": "ListAvailableSessions",
                    "url": "https://customer.cloud.com/api/store/sessions",
                    "capability": [
                        "ListAvailableSessions"
                    ]
                },
                {
                    "id": "ListResources",
                    "url": "https://customer.cloud.com/api/store/resources",
                    "capability": [
                        "ListResources"
                    ]
                },
                {
                    "id": "ValidateConnection",
                    "url": "https://customer.cloud.com/api/store/connection/validationStatus",
                    "capability": [
                        "ValidateConnection"
                    ]
                }
            ],
            ...
        }
    ],
    "authScopes": [
        "wsp"
    ],
    "clientSettings": {
        "customerDomain": "customer.cloud.com",
        "customerId": "{CUSTOMER_ID}",
        "authDomain": "{AUTH_DOMAIN}",
        "lockedDown": true,
        "webUiCapabilities": "MobileReceiverReady",
        "products": [...],
        "storeGuid": "{GUID}",
        "oidcConfiguration": {
            "oidc_discovery_endpoint": "https://accounts.cloud.com/core/.well-known/openid-configuration",
            "oidc_clients": {...}
        },
        "serviceRecordId": "{SERVICE_RECORD_ID}",
        "inactivityTimeoutInMinutes": "1440",
        "inactivityTimeoutInMinutesMobile": null,
        "acr_values": "{ACR_VALUES}",
        "promptLoginEnabled": true,
        "disallowICADownload": false
    }
}
<!--NeedCopy-->

Throughout this documentation, endpoint URLs are representative. You should always use the URLs defined by the Configuration JSON.

Authentication

Some endpoints are protected and require an OAuth access token to allow access. If the required token is not present, or you include a token but it has expired, the API returns a response with HTTP status code 400 and a response body.

For example if the first call is to resource enumeration and you don’t yet have a token:

curl https://customer.cloud.com/api/store/resources --header "Citrix-ApplicationId: {APPLICATION_ID}"
<!--NeedCopy-->

Response:

{
    "error": "invalid_grant",
    "error_description": "Access token is invalid."
}
<!--NeedCopy-->

To obtain an access token and find out more about the API authentication, read our authentication guide.

List Sessions

To get a list of active sessions, use the returned URL provided in the discovery configuration document with ID ListAvailableSessions.

You will need to provide a excludedClientName query parameter, this is used to avoid a client performing a re-connection when the connection exists already on the current client, e.g. the session is active on the current client rather than a different client.

Session re-connect

To perform a session re-connect on one of the above sessions, make a POST request to the launchUrl.

For example:

curl -X POST 'https://customer.cloud.com/api/store/sessions/{SESSION_ID}/$launch?clientName={CLIENT_HOSTNAME}&deviceId={CLIENT_HOSTNAME}&clientAddress={CLIENT_IP_ADDRESS}' --header "Citrix-ApplicationId: {APPLICATION_ID}" --header "Authorization: Bearer $token" 
<!--NeedCopy-->

As outlined here we have set the client name and device id as the client computers hostname. This will be used later during session disconnect.

If the session is ready to launch then this will return an ICA file with content type application/x-ica, for example:

[Encoding]
InputEncoding=UTF8

[WFClient]
ProxyFavorIEConnectionSetting=Yes
ProxyTimeout=30000
ProxyType=Auto
ProxyUseFQDN=Off
RemoveICAFile=yes
TransportReconnectEnabled=On
<Rest of ICA file content, omitted for brevity>
<!--NeedCopy-->

Clients typically load the launchUrl URL into an iframe to obtain an ICA file and trigger a launch via file type association. The HDX client will use the information in the ICA file to create a session to the resource.

Resource Enumeration

To get a list of resources available to the user, use the returned URL provided in the discovery configuration document with ID ListResources.

The response body is a JSON object that includes an array of resources and links to perform operations on those resources.

For example:

curl https://customer.cloud.com/api/store/resources --header "Citrix-ApplicationId: {APPLICATION_ID}" --header "Authorization: Bearer $token"
<!--NeedCopy-->

Response (simplified for brevity):

{
    "resources": [
        {
            "resourceId": "{RESOURCES_ID}",
            "id": "{ID}",
            "name": "Microsoft Word",
            "links": {
                "resourceDetailsUrl": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}",
                "imageUrl": "https://cdn.azureedge.net/{RESOURCES_ID}.png",
                "launchUrl": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/icaFile",
                "launchStatusUrl": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/tickets",
                "favoriteUrl": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/$favorite",
                "unfavoriteUrl": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/$unfavorite",
                "resourcePreferences": "https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/preferences"
            },
            "path": "\\Office Apps\\",
            "disabled": false,
            "keywords": [],
            "clientTypes": [
                "ica30",
                "rdp"
            ],
            "resourceType": "Citrix.MPS.Application",
            "properties": [],
            "playsFileTypes": [],
            "mandatory": false,
            "recentsPosition": 4
        },
        ...
    ]
}
<!--NeedCopy-->

For each resource, this includes the operation endpoints that can be used to perform actions such as launch the resource.

Launch Resource

To launch the resource, make a GET request to the launchUrl endpoint returned by the response above.

For example:

curl https://customer.cloud.com/api/store/resources/{RESOURCES_ID}/icaFile?clientName={CLIENT_HOSTNAME}&deviceId={CLIENT_HOSTNAME}&clientAddress={CLIENT_IP_ADDRESS} --header "Citrix-ApplicationId: {APPLICATION_ID}" --header "Authorization: Bearer $token"
<!--NeedCopy-->

As outlined here we have set the client name and device id as the client computers hostname. This will be used later during session disconnect.

If the session is ready to launch then this will return an ICA file with content type application/x-ica, for example:

[Encoding]
InputEncoding=UTF8

[WFClient]
ProxyFavorIEConnectionSetting=Yes
ProxyTimeout=30000
ProxyType=Auto
ProxyUseFQDN=Off
RemoveICAFile=yes
TransportReconnectEnabled=On
<Rest of ICA file content, omitted for brevity>
<!--NeedCopy-->

The ICA file contents can then be saved locally to disk in a temporary file and opened to trigger a HDX launch. More information about the supported launch flows can be found here.

Logoff and Disconnect

The client should give the ability to disconnect and logoff from active sessions.

Disconnect

To disconnect an active session, use the Resources Disconnect API.

Once disconnected, the client can later re-connect by calling List Sessions.

For example:

curl -X POST 'https://customer.cloud.com/api/store/sessions/$disconnect' --header "Authorization: Bearer $token" --header "Citrix-ApplicationId: {APPLICATION_ID}" --header "Content-Type: application/json" --data '{"clientName": "{CLIENT_HOSTNAME}", "deviceId": "{CLIENT_HOSTNAME}"}'
<!--NeedCopy-->

The CLIENT_HOSTNAME must match what was sent during session re-connect and resource launch.

Response will be a status code of 200 OK if all sessions are fully disconnected or 206 partial success which means sessions are being disconnected in the background.

The indication that this has worked will be that all launched sessions will disconnect.

Logoff

The session logoff endpoint can be used to close all sessions and invalidate unused launch tickets.

For example:

curl -X POST 'https://customer.cloud.com/api/store/sessions/$logoff' --header "Citrix-ApplicationId: {APPLICATION_ID}" --header "Authorization: Bearer $token" --header "Content-Type: application/json" --data '{"clientName": "{CLIENT_HOSTNAME}", "deviceId": "{CLIENT_HOSTNAME}"}'
<!--NeedCopy-->

The CLIENT_HOSTNAME must match what was sent during session re-connect and resource launch.

Response will be a status code of 200 OK if all sessions are fully disconnected or 206 partial success which means sessions are being disconnected in the background.

The indication that this has worked will be that all launched sessions will disconnect.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Getting Started

April 29, 2024

Contributed by:

April 29, 2024

Contributed by:

Getting Started

API usage pattern

Hypermedia Control and Parameterized URLs

HTTP POST Parameters

Fetch the Discovery Configuration

Authentication

List Sessions

Session re-connect

Resource Enumeration

Launch Resource

Logoff and Disconnect

Disconnect

Logoff

In this article