Workspace Discovery API Documentation

Discovery

The Discovery API helps you determine the service URLs that are available for the client, as well as the customer metadata that is necessary for the client operation.

Open API spec is available via your customer URL https://customer.cloud.com/api/swagger/index.html?urls.primaryName=discovery.

Notes:

• Replace ‘customer.cloud.com’ with your Workspace URL.
• 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.
• Does not require an authorization token.
• Response may contain one or many service entries in the service list.
• A service represents a grouped set of APIs with operations that relate to a similar domain.
• A service entry can contain one or many API endpoints with an optional capability list.
• The client can reference endpoints by “id” and services by “service” (name) as they are constant.

Store

The Open API spec will be available via your customer URL https://customer.cloud.com/api/swagger/index.html?urls.primaryName=store.

Notes:

• Replace ‘customer.cloud.com’ with your Workspace URL.
• 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.

Authentication

The Authentication API contains endpoints that are protected by OAuth. You need to provide an Authorization header containing the OAuth Access token, e.g. "Authorization" = "Bearer <token>". If a valid Authorization header isn’t provided, the request fails with a 400 Bad Request response, with the reason stated as invalid_grant.

For example:

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

To obtain an Access Token, follow the Authentication walkthrough.

Client Name and Device ID

When a client communicates with certain API endpoints, either one or both of clientName and deviceId is required.

• Client Name: Used to identify the client in broker policies. This should be the computer hostname. If the hostname is not available then you should use an alternative identifier for the device.
• Device ID: This is used to identify a device when using the Workspace Control feature. It is recommended to use the same deviceId consistently for a specific device. Typically the computer hostname is used, but you can use an alternative value as long as it uniquely and consistently identifies a device.

It is recommended to set the same value for clientName and deviceId but it is not a requirement.

Supported Launch Flows

The following sequence diagrams give a more detailed view on how you can use the Unified Workspace APIs to perform ICA launches, from the perspective of a Single Page Application.

Unified Workspace API currently only supports launching resources that have the ica30 clientType that can be found during resource enumeration.

Windows Ticketed ICA Launch

This launch flow should be used for the Web application use-case. Refer to the Single Page Application sample to see how this has been implemented.

A ‘Ticketed’ launch is used here because the OAuth access token cannot be provided directly to the Citrix Workspace App Web Helper.

The endpoint that the single page application needs to call is the value of launchStatusUrl returned from the resource enumeration response.

The response from the launchStatusUrl will either be a retry required (202) JSON response, containing details such as the retryUrl, retryKey and pollTimeout, or launch ticket created (201) JSON response.

The launch ticket created response, will be a JSON object with receiverUri that can then be opened by the browser via a redirect. This opens a new tab in the browser and a popup will appear with the title ‘Open the Citrix Workspace Launcher?’, selecting ‘Open’ will trigger the Citrix Workspace App Web Helper.

The receiverUri contains a one-time ticket as part of the query string, which is used for authentication. This will trigger protocol handling so the Citrix Workspace App Web Helper can perform the launch.

ICA File Download Launch

This launch flow should be used for the Native application use-case. Refer to the Native Client sample to see how this has been implemented.

The Native application needs to call the launchUrl returned from the resource enumeration response.

The response from the launchUrl will either be a retry required (202) JSON response, containing details such as the retryUrl, retryKey and pollTimeout, or an ICA file response (200).

The Native client can then save the contents of the ICA file to disk with a .ica file extension and start a new process pointing to that file. This will trigger a HDX launch.