Get started with Citrix Cloud APIs

Citrix Cloud services simplify the delivery and management of Citrix technologies, helping you to extend existing on-premises software deployments or move one hundred percent to the cloud.

Get access to Citrix Cloud

A Citrix Cloud account is required to use Citrix Cloud Services APIs. If you are a new user, you can Sign up for a free Citrix Cloud account. More information.

To get started log in to Citrix Cloud.

Create an API client

To call APIs, you must create an API client in 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. 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.

   

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

   

5. The following message appears, ID and Secret have been created successfully. Download or copy the Client Id and Secret. You will need both to access the APIs.

   

6. After closing the previous dialog, take a note of the customer ID in the description above the Create Client button. You will also need this to access the APIs.

   

Generate a bearer token

When calling Citrix Cloud APIs, a bearer token is used for API authentication and authorization.

In case you prefer a hands-on walkthrough with code examples, proceed with the Citrix Cloud API walkthrough.

Bearer Token Tab {.tabnav}

OAuth 2.0 Flow

For calling APIs using an integration (implemented in PowerShell, Python, app, script, etc.), tokens can be obtained using a standard OAuth 2.0 Client Credential grant flow. For more information about OAuth 2.0 Client Credential grant, see https://tools.ietf.org/html/rfc6749#section-4.4.

To get a bearer token, make a POST call to the trust service’s authentication API as shown below:

POST https://api-us.cloud.com/cctrustoauth2/{customerid}/tokens/clients

Note:

Use one of the following endpoints based on the geographical region you selected while creating the Citrix Cloud account:

• api-ap-s.cloud.com – If your Citrix Cloud account is set to the Asia Pacific South region.
• api-eu.cloud.com – If your Citrix Cloud account is set to the European Union region.
• api-us.cloud.com – If your Citrix Cloud account is set to the United States region.
• api.citrixcloud.jp - If your Citrix Cloud account is set to the Japan region.

Request sample:

POST https://api-us.cloud.com/cctrustoauth2/root/tokens/clients HTTP/2
Accept: application/json
Content-Type: application/x-www-form-urlencoded


grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
<!--NeedCopy-->

Response sample:

HTTP/1.1 200 OK
Content-Type: application/json
...


{
    "token_type": "bearer",
    "access_token": "ey1..",
    "expires_in": "3600"
}
<!--NeedCopy-->

The required bearer token is the value of the response parameter access_token. When using this parameter, prefix this value with CwsAuth Bearer=.

For example, Authorization: CwsAuth Bearer=ey1..

Manual: Developer Portal Flow

For manual API interactions tokens can be generated using the Developer Portal UI.

1. Navigate to any Citrix Cloud service on the developer portal. On the API Exploration tab, click on any API from the list. Click on the Invoke API button.

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

3. Enter Client ID and Secret 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.

Deprecated: Trust Service Flow

Warning:

While there is no planned End Of Life, the legacy Trust Service API is deprecated and should no longer be used for new applications. Use the OAuth 2.0 Flow instead.

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

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

Request sample:

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


{"ClientId":"<your_client_ID>", "ClientSecret": "<your_client_secret>" }
<!--NeedCopy-->

Response sample:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...


{
  "principal": "john.down@citrix.com",
  "subject": "16..",
  "token": "ey1..",
  "openIdToken": "ey1..",
  "expiresIn": 3600
}
<!--NeedCopy-->

The required token is the value of the parameter token in the response. The bearer token can now be used to authenticate calls to any Citrix Cloud API. Prefix this value with CwsAuth Bearer=.

For example, Authorization: CwsAuth Bearer=ey1...

Note:

Bearer tokens are typically valid for an hour, after which they expires (refer to the response field expires_in). In that case, follow the same steps to generate a new token.

{}

Next steps

Refer to the Citrix Cloud API Walkthrough to get hands-on. Or browse the portal to learn about all available Services and their APIs.

You can get access to additional Citrix Cloud Services using either:

• Microapps Service Developer Test instance
• Trials
• Purchases

API client scope and permissions

API clients in Citrix Cloud are always tied to one administrator and one customer. API clients are not visible to other administrators. If you want to access to more than one customer, you must create API clients within each customer.

API clients are automatically restricted to the rights of that administrator that created it. For example, if an administrator is restricted to access only notifications, then the administrator’s API clients have the same 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 of the administrator’s API clients are also removed.