Getting started with the Secure Private Access on-premises API

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

Placeholder Values

In this document, any text enclosed in curly braces {} represents a placeholder for a variable value. For example, { hostUrl } must be replaced with the actual host URL.

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.

The following must also be specified in each API request:

• The Authorization header must be set to a valid bearer token. Otherwise, a 401 Unauthorized error response is received.
• The Accept header must always be set to application/json. Otherwise, a 406 Not Acceptable error response is received.
• For POST or PUT requests where a request body is present, the Content-Type header must be set to application/json; charset=utf-8. Not doing so results to a 415 Unsupported Media Type error response. All data provided in the request bodies must be in the appropriate JSON formats.
• Upon receipt of a Citrix-TransactionId header following the initial request, the same header with the identical value must be included in subsequent requests. This facilitates the tracing of request and response flows in case support is required. Although the Citrix-TransactionId header is not strictly necessary for processing an operation, a new one is provided in a response if one is not included in the request.
• Host and Content-Length headers are required for all requests.

In all cases where results are returned, they can be expected to be in JSON format.

Authorization credentials

Getting an authorization bearer token

To obtain an authorization bearer token, a username, password, and the domain associated with this account are required. This token is required for making requests to the Secure Private Access API. Ensure that the domain controller is properly configured to authenticate these credentials.

POST request:

POST https://{ hostUrl } : { port }/admin/signin

with a body of:

{
    "username": "client's Username",
    "password": "client's Password",
    "domain": "associated Domain"
}
<!--NeedCopy-->

The response has a body set to 1, a response code of 200 and the bearer token as value of the Authorization response header.

Required headers for a successful request:

Content-Length: { appropriate length },
Host: { appropriate address }, 
Content-Type: application/json; charset=utf-8
Accept: application/json
<!--NeedCopy-->

Errors

For error responses, such as 400 BAD REQUEST, 406 NOT ACCEPTABLE, 415 UNSUPPORTED MEDIA TYPE, 500 INTERNAL SERVER ERROR, a response body with more details is expected. The body is in the following JSON 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-->

API specification

The OpenAPI specification is available in the url:

https://{ hostUrl } : { port }/accessSecurity/swagger

where it can also be downloaded as a json file.