Getting started with the Secure Private Access API

The topic captures the basic information on using the Secure Private Access API.

Points to note

To use the Secure Private Access API, use the service URL defined in the OpenAPI specification and https protocol for all your requests.

You must also specify the following in each API request:

• Set the Authorization and Citrix-CustomerId headers appropriately by using the right Customer ID for the admin account and a valid bearer token. Else, you get the 401 Unauthorized error response. For more details, see Authorization Credentials.
• Always set the Accept header as application/json. Else, you get the 406 Not Acceptable error response.
• For POST or PUT requests where a request body is sent, set the Content-Type header as application/json; charset=utf-8. Else, you get the 415 Unsupported Media Type error response. All data provided in the request bodies must be in the appropriate JSON formats.
• Once you receive a Citrix-TransactionId header after your first request, continue to provide the same header with the same value so that a flow of requests and responses can be easily traced in case support is needed. The Citrix-TransactionId header is not strictly required for an operation to be processed. If not set in a request, a new one is provided in the response.

In all cases where results are returned, you can expect them to be in JSON format.

Authorization credentials

Creating an API client

If you don’t have an API client, you can create one. For details, see Getting started section for Citrix Cloud. When you create a client, client_secret and a client_id are generated. The client ID and client secret are required to generate an authentication token.

Getting the Citrix customer ID

Each request requires a Citrix customer ID passed through a header. To get the customer ID:

• Log in to the Citrix Cloud.
• Select the Identity and Access Management option from the hamburger menu.
• Click API Access. The customer ID is displayed in the description above the Create Client button.

Getting an authorization bearer token

Using the {{clientId}}, {{clientSecret}}, and the {{Citrix-CustomerId}}, you can get an authorization bearer token that you can use in your requests to the Secure Private Access API.

POST request:

POST https://api.cloud.com/cctrustoauth2/{{Citrix-CustomerId}}/tokens/clients

with a body of:

{
    "clientId": "\{\{clientId\}\}",
    "clientSecret": "\{\{clientSecret\}\}"
}
<!--NeedCopy-->

and you can expect a response with a body as follows that you can parse and use the value of the token property as the bearer token in the authorization header.

{
    "principal": "...",
    "locale": "en-US",
    "subject": "...",
    "token": "...",
    "openIdToken": "...",
    "expiresIn": 3600
}
<!--NeedCopy-->

Errors

For the errors, such as 400 BAD REQUEST, 406 NOT ACCEPTABLE, 415 UNSUPPORTED MEDIA TYPE, 500 INTERNAL SERVER ERROR, you can expect a response body in JSON with more details, in the following format:

{
    "type": "https://errors-api.cloud.com/common/Error",
    "detail": "Input payload validation failed",
    "parameters": [
        {
            "name": "priority",
            "value": "167.72 is not of type 'integer'"
        },
        {
            "name": "active",
            "value": "1 is not of type 'boolean'"
        }
    ]
}
<!--NeedCopy-->

Rate limits

Call rates are limited to 10 calls per 5 seconds for API requests. If the rate limit is surpassed, the requests result in 429 Too Many Requests responses. In such case, consider introducing some delay between your requests.

Call rates are limited to 10 calls per 5 seconds for API requests.

API specification

You can also get the OpenAPI specification file directly from the service, in YAML or JSON format, with a GET request:

GET https://api.cloud.com/accessSecurity/apiSpecification

Specify the following headers for a JSON formatted file:

...
Accept: application/json
Citrix-CustomerId: \{\{customerId\}\}
Authorization: CWSAuth Bearer=\{\{bearerToken\}\}
Citrix-TransactionId: \{\{Citrix-TransactionId\}\}
...
<!--NeedCopy-->

or with Accept: application/x-yaml for a YAML formatted file.