Getting started

API usage pattern

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

1. Fetch the site configuration, to determine behavior and discover URLs for subsequent operations.
2. Authentication, to allow access to resources.
3. List resources, to display resources to the user and get the information required to launch them.
4. Launch resources in response to user actions in the UI.
5. Log off

Fetch site configuration

The first step is to call Home/Configuration.

curl "https://storefront.example.com/Citrix/StoreWeb/Home/Configuration" ^
  -X "POST" ^
  -H "Content-Length: 0" ^
  -H "User-Agent: My Application" ^
  -H "X-Citrix-IsUsingHTTPS: Yes"
<!--NeedCopy-->

This returns an XML document describing various Citrix Receiver for Web configuration settings, including a number of URL paths (relative to the site root) that the client must use for subsequent API calls. For example:

<clientSettings xmlns='http://citrix.com/delivery-services/webAPI/2-6/clientConfig'>
    <session timeout="20" userLanguages="en-US,en;q=0.5" />
    <authManager
        getUsernameURL="Authentication/GetUserName"
        changeCredentialsURL="Authentication/GetChangeCredentialForm"
        logoffURL="Authentication/Logoff"
        loginFormTimeout="5" />
    <storeProxy keepAliveURL="Home/KeepAlive">
        <resourcesProxy listURL="Resources/List" resourceDetails="default" />
        <sessionsProxy
            listAvailableURL="Sessions/ListAvailable"
            disconnectURL="Sessions/Disconnect"
            logoffURL="Sessions/Logoff" />
        <clientAssistantProxy
            getDetectionTicketURL="ClientAssistant/GetDetectionTicket"
            getDetectionStatusURL="ClientAssistant/GetDetectionStatus" />
    </storeProxy>
    <pluginAssistant enabled="true" upgradeAtLogin="true">
        <win32 path="http://downloadplugins.citrix.com/Windows/CitrixReceiverWeb.exe" />
        <macOS path="http://downloadplugins.citrix.com/Mac/CitrixReceiverWeb.dmg" 
            minimumSupportedOSVersion="10.6" />
        <html5
            enabled="Off"
            platforms="Firefox;Chrome;Version/([6-9]|\d\d).*Safari;MSIE\d\d;Trident/([6-9]|\d\d);Android;iPad;iPhone;iPod;"
            launchURL="clients/HTML5Client/src/SessionWindow.html"
            preferences=""
            singleTabLaunch="false"
            chromeAppOrigins="chromeextension://haiffjcadagjlijoggckpgfnoeiflnem|chromeextension://bgiigkppjadidglloadcadeihlnbpagp" />
        <protocolHandler
            enabled="true" skipDoubleHopCheckWhenDisabled="false"
            platforms="(Macintosh|Windows NT).*Chrome/((4[2-9]|[56789][0-9])|\d\d\d)(?!.*Edge)" />
    </pluginAssistant>
    <userInterface autoLaunchDesktop="true" multiClickTimeout="3" enableAppsFolderView="true">
        <workspaceControl
            enabled="true" autoReconnectAtLogon="true" logoffAction="disconnect"
            showReconnectButton="true" showDisconnectButton="true" />
        <receiverConfiguration enabled="true"
            downloadURL="ServiceRecord/GetDocument/receiverconfig.cr" />
        <uiViews showDesktopsView="true" showAppsView="true" defaultView="auto" />
        <appShortcuts enabled="false" allowSessionReconnect="false" />
    </userInterface>
</clientSettings>
<!--NeedCopy-->

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

As this is the first request, the response sets the following cookies that must be included in subsequent requests:

• ASP.NET_SessionId which identifies the session.
• Csrf-Token to prevent cross-site request forgery. The value must be included as a header in subsequent requests.

Authentication

Some endpoints are protected and require authentication information to allow access. If the required authentication information is not present, the API returns a response with HTTP status code 200 and a challenge in the form of a CitrixWebReceiver-Authenticate header.

For example, first make a POST request to Resources/List.

curl "https://storefront.example.com/Citrix/StoreWeb/Resources/List" ^
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" ^
  -H "Cookie: CsrfToken=3FF6BD3BB54A0EA7976D8F9C4C663D6A; ASP.NET_SessionId=5bkxugjoy0l5kg0tgdctsvhq" ^
  -H "Csrf-Token: 3FF6BD3BB54A0EA7976D8F9C4C663D6A" ^
  -H "User-Agent: My Application" ^
  -H "X-Citrix-IsUsingHTTPS: Yes" ^
  --data-raw "format=json&resourceDetails=Default"
<!--NeedCopy-->

Since the user is not yet authenticated, this returns a response of {"unauthorized": true} with the following header:

CitrixWebReceiver-Authenticate: reason="TokenRequired",  location="Authentication/GetAuthMethods"
<!--NeedCopy-->

The location value in the challenge specifies a URL that the client can request in order to determine which authentication methods are available. The challenge may contain an additional attribute mode=Redirect, which triggers the client to redirect to a third party page to perform the authentication there instead. The next step is to call this endpoint to get the list of authentication methods. The client must not skip this request by hard-coding any of the authentication URLs, as they may change from release to release.

Next, call the Authentication/GetAuthMethods endpoint.

curl "https://storefront.example.com/Citrix/StoreWeb/Authentication/GetAuthMethods" 
  -X "POST" ^
  -H "Cookie: CsrfToken=3FF6BD3BB54A0EA7976D8F9C4C663D6A; ASP.NET_SessionId=5bkxugjoy0l5kg0tgdctsvhq" ^
  -H "Csrf-Token: 3FF6BD3BB54A0EA7976D8F9C4C663D6A" ^
  -H "User-Agent: My Application" ^
  -H "Content-Length: 0" ^
  -H "X-Citrix-IsUsingHTTPS: Yes"
<!--NeedCopy-->

If successful, the response body contains an XML document with root node authMethods and zero or more method child elements. For example:

<?xml version="1.0" encoding="UTF-8"?>
<authMethods xmlns="http://citrix.com/delivery-services/webAPI/2-6/authMethods">
    <method name="IntegratedWindows" url="DomainPassthroughAuth/Login"/>
    <method name="Certificate" url="SmartcardAuth/Login"/>
    <method name="ExplicitForms" url="ExplicitAuth/Login"/>
</authMethods>
<!--NeedCopy-->

Each method child element contains a name attribute identifying the authentication method and a url attribute that the client uses to initiate authentication using the given method. The possible authentication method names are:

Once the user is authenticated, StoreFront sets the cookie CtxsAuthId which must be included in subsequent requests until the user is logged off.

Note:

Even after the user has authenticated, a challenge may be returned. For example, if the client’s session has terminated for any reason, the ASP.NET_SessionId cookie is absent from the client request, or if the StoreFront credential wallet service has restarted. Therefore, the client must be prepared to respond to such an authentication challenge at any time by prompting the user to re-authenticate to the site.

List resources

To get a list of resources available to the user, use the Resources/List endpoint.

curl "https://storefront.example.com/Citrix/StoreWeb/Resources/List"   -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" ^
  -H "Cookie: CtxsDeviceId=WR_M634tCXrAJIG; CsrfToken=3FF6BD3BB54A0EA7976D8F9C4C663D6A; CtxsAuthId=B0DD984789210138A3FC64052C9540E0; ASP.NET_SessionId=5bkxugjoy0l5kg0tgdctsvhq" ^
  -H "Csrf-Token: 3FF6BD3BB54A0EA7976D8F9C4C663D6A" ^
  -H "User-Agent: My Application" ^
  -H "X-Citrix-IsUsingHTTPS: Yes" ^
  --data-raw "format=json&resourceDetails=Default"
<!--NeedCopy-->

The response body is a JSON object that includes an array of resources. For example (simplified for brevity):

{
    "resources":[
        {"clienttypes":["ica30","rdp"],
        "description":"",
        "iconurl":"Resources\/Icon\/NUM2RDNDRDU1QzdBMUE0RjU0NjA4NjRBNTkwMzY0NzQyM EM2OTQ3QQ--\/48",
        "id":"Q29udHJvbGxlci4hJCVeJl8rLQ--",
        "launchurl":"Resources\/LaunchIca\/Q29udHJvbGxlci4hJCVeJl8rLQ--",
        "name":"Microsoft Word",
        "path":"\\Office Apps\\",
        "shortcutvalidationurl":"Resources\/ValidateAppShortcutLaunch\/Q29udHJvbG xlci4hJCVeJl8rLQ--",
        "subscriptionstatus":null,
        "subscriptionurl":"Resources\/Subscription\/Q29udHJvbGxlci4hJCVeJl8rLQ--"
        },
        {
        "clienttypes":["ica30","rdp"],
        "description":"",
        "disabled":true,
        "iconurl":"Resources\/Icon\/NUM2RDNDRDU1QzdBMUE0RjU0NjA4NjRBNTkwMzY0NzQyMEM2OTQ3QQ--\/48",
        "id":"Q29udHJvbGxlci4hJF4kJV4-",
        "launchurl":"Resources\/LaunchIca\/Q29udHJvbGxlci4hJF4kJV4-",
        "name":"!$^$%^",
        "path":"\\Yabba\\",
        "shortcutvalidationurl":"Resources\/ValidateAppShortcutLaunch\/Q29udHJvbG xlci4hJF4kJV4-",
        "subscriptionstatus":null,
        "subscriptionurl":"Resources\/Subscription\/Q29udHJvbGxlci4hJF4kJV4-"
        }
    ],
    "subscriptionsEnabled":true,
}
<!--NeedCopy-->

For each resource, this includes the endpoint that can be used to launch the resource.

It is recommended you include a cookie CtxsDeviceId containing the machine name, or other identifier unique to the device. If you do not include this cookie then StoreFront generates a unique value and returns it as a cookie. This cookie should be included in subsequent requests. For more information see DeviceId.

Launch resource

To launch the resource, make a GET request to the endpoint returned by the Resources/List endpoint, for example Resources/LaunchIca/Q29udHJvbGxlci4hJCVeJl8rLQ--:

curl "https://storefront.example.com/Citrix/StoreWeb/Resources/GetLaunchStatus/RGFhUyBDbG91ZC5DYWxjdWxhdG9yIENsb3Vk" ^
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" ^
  -H "Cookie: CtxsDeviceId=WR_M634tCXrAJIG; CsrfToken=3FF6BD3BB54A0EA7976D8F9C4C663D6A; CtxsAuthId=B0DD984789210138A3FC64052C9540E0; ASP.NET_SessionId=jc0ljky5rsxzys1xdnelvoj0" ^
  -H "Csrf-Token: 3FF6BD3BB54A0EA7976D8F9C4C663D6A" ^
  -H "User-Agent: My Application" ^
  -H "X-Citrix-IsUsingHTTPS: Yes" ^
  --data-raw "createFileFetchTicket=true"
<!--NeedCopy-->

If the session is ready to launch then this returns 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 save this as an .ica file and existe it using the installed Workspace app. Workspace app uses the information in the ICA file to create a session to the resource.

If the session is not ready to launch then it responds with the request body containing the status, as would be returned by Session/LaunchStatus, with content type text/plain, for example if the launch fails then it returns:

{"status":"failure"}
<!--NeedCopy-->

Alternatively if the resource is not currently ready it could respond that the client should try again in 5 seconds:

{"status":"retry","pollTimeout":5}
<!--NeedCopy-->

Log-off

Before logging off the user, optionally disconnect or log off the user’s sessions. Then log off the user from StoreFront.

Cookies

StoreFront sets a number of cookies as outlined in the following table.

The client must return the cookies in subsequent requests, as indicated by the cookie life time.

DeviceId

Some API calls require the client to identify the device it is being called from via the DeviceId. This is used in two ways. Firstly it is passed through to the delivery controller as the ClientName and can be used in policies to determine which apps are available. Secondly, it is used to track which device each session has been launched on, which can be used to find and connect to sessions on other devices and disconnect the current device’s sessions.

The client should set the cookie CtxsDeviceId to the computer name if possible, otherwise an alternative unique identifier for the device. If the client does not include this cookie when listing resources then StoreFront generates a unique string and returns it as a cookie to be used in subsequent requests.

HTTPS indicator to secure cookies

Unless specified otherwise, the Web API requires the client to indicate whether it is using an HTTPS connection or not. For POST requests the client must supply a header named X-Citrix-IsUsingHTTPS with value “Yes” or “No”, and for GET requests the client must supply a query string parameter named IsUsingHttps, again with value “Yes” or “No”. When the indicator is not present or has any value other than “No”, StoreFront sets the Secure attribute for all cookies that it generates to protect them from being viewed from non-HTTPS connections. This caters for NetScaler Gateway scenarios where the connection from the browser to the gateway is over HTTPS but the connection from the gateway to StoreFront is HTTP.

Cross-site request forgery token

To protect against cross-site request forgery (CSRF) attacks, the Web APIs require that a CSRF token be supplied by the client, unless specified otherwise. This is a random string generated by the Web Proxy for the duration of the session and communicated to the client using a session cookie, set in the response to the client’s first request. Clients must read the value of this cookie and send it back to the Web Proxy in most API calls, as either the value of a header named Csrf-Token (note the hyphen) for POST requests, or as the value of a query string parameter named CsrfToken for GET requests.

Localization

Generally, the StoreFront Web API does not return user-facing strings to display in a UI. However, if using Explicit Forms authentication, the authentication process uses the Citrix Common Forms protocol to obtain a definition of the logon form (amongst other forms), which typically includes strings for UI controls (for example, a “Username: “ label or “Log On” button). The value specified in the Accept-Language HTTP header is used to determine the language for such strings. This value is also reflected back to the client in the response to the /Home/Configuration request so that the client may perform any additional localization to match the language used for authentication forms.

HTTP POST Parameters

Throughout the API, any request parameters in the POST body must follow standard form URLencoding rules, with Content-Type set to:

application/x-www-form-urlencoded
<!--NeedCopy-->