Log in to Citrix Cloud account
 
Create an API Client
 
Call an API
Log in to Citrix Cloud account

To use Citrix Cloud Services APIs a Citrix Cloud account is required.

  1. If you are a new user, you must Sign up for a Citrix Cloud account. See Signing Up for Citrix Cloud for more information.
  2. If you are an existing user, use your credentials to log in to your Citrix Cloud account.
Create an API client

To call APIs from a script or an external program, you must create an API client in the Citrix Cloud.

  1. In the Citrix Cloud console, click the menu in the upper left corner of the screen.

  2. Select the Identity and Access Management option from the menu.

    Note: If this option does not appear, you may not have adequate permissions to create an API client. Contact your administrator to get the required permissions.

  3. Select the API Access tab.

     

    Important: Take a note of the customer ID in the description above the Create Client button. You will need it in the later steps.

  4. Name your Secure Client, and click Create Client.

    Note: Deleting a client can impact your integration with Citrix Cloud.

     
  5. The following message appears, ID and Secret have been created successfully. Download or copy the Client Id and Secret.

    Important: Citrix recommends that you use the Client Id and Secret to obtain the bearer token required to authenticate Citrix APIs. For further information, check the Call an API section.

API client scope and permissions

API clients in Citrix Cloud are always tied to one administrator and one customer. The API clients that you create are not visible to other administrators in your organization. If you have access to more than one customer, you must create API client(s) within each customer. You can use these clients to call APIs for these customers.

API clients owned by a Citrix Cloud administrator are automatically restricted to the rights of that administrator, within that customer. For example, if an administrator is restricted to access only notifications, then the API clients also have similar restrictions.

If an administrator’s access is reduced at any point, then the access of all the API clients owned by that administrator is also reduced.

If an administrator’s access is removed from the list of administrators within that customer, then all the API clients within that customer are automatically deleted.

Customer ID

The Citrix Cloud API requires a customer ID when calling REST APIs, either as part of the URL or as part of the request headers. The parameter must be the special value root or the specific customer that you are targeting depending on the API specification.

To get the customer ID, go to the Identity and Access Management page and click API Access tab. You can see the customer ID in the description above the Create Client button.

 
Call an API

In order to call an API, a bearer token is required. Citrix recommends using the Client ID and Secret method to generate a bearer token. This can be done either in the developer portal UI or by making a call to the Trust Service (this is useful while writing third-party scripts in Powershell, Python, etc).

Generating bearer token using developer portal UI

  1. Navigate to any Citrix Cloud service in the developer portal. Under API Exploration tab, click on any API from the list. Click Try this API button.

  2. In the request Authorization header parameter description, click Generate here. The Set Authentication window appears.

  3. Enter Client ID and Secret keys that were generated while creating an API client. Click Generate. A bearer token is generated using the Client ID and Secret and populated in the Authorization header field.

Generating bearer token using Trust Service API

Make a POST call to the trust service's authentication API as shown below: 

POST https://trust.citrixworkspacesapi.net/{customer}/tokens/clients

Parameter Parameter Type Value
customer path Use the special value root, if feasible.
Accept header application/json
Content-Type header application/json
 

 

Request sample

Request headers

POST https://trust.citrixworkspacesapi.net/root/tokens/clients HTTP/1.1
Accept: application/json
Content-Type: application/json

Request body

{"ClientId":"<your_client_ID>", "ClientSecret": "<your_client_secret>" }

Response sample

HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 2623
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Dec 2016 21:53:37 GMT
X-Cws-TransactionId: 6c3db4d6-125f-4ea3-b938-882bc5dc3caf

{
  "principal": "john.down@citrix.com",
  "subject": "16..",
  "token": "ey1..",
  "openIdToken": "ey1..",
  "expiresIn": 3600
}

The required token is the value of the parameter token in the response obtained. Prefix this value with CwsAuth Bearer=

For example, Authorization: CwsAuth Bearer=ey1..

Call an API using the bearer token obtained

Using the bearer token generated using either method can now be used to call any Citrix Cloud API. Note that the bearer token is normally valid for an hour, post which it expires. In that case, follow the steps mentioned above to generate the token again.