Handling applications with Secure Private Access on-premises API

This topic provides instructions on how to create, list, update, and delete applications using the Secure Private Access API. Before starting with this API, understand the mandatory headers for all the requests listed in Getting Started.

Applications object schema in request / response body

Each application object in the items array follows the schema below. Each property value is given as a string unless differently specified.

• state (optional). State of the application. Takes one of incomplete and complete values.
• name. The name of this application.
• type. The type of the application. Takes one of web, saas, and ztna values.
• description (optional). Description of this application.
• category (optional). Category of this application.
• keywords (optional). Keywords relevant to this application.
• url (optional). Application URL. This field is required when creating non-ZTNA (secure) applications.
• sbsOnlyLaunch (optional). Force launch app in Secure Browser Service.
• mobileSecurity (optional). Enforce enhanced security on mobile applications.
• customerDomainFields (optional). JSON object containing customer domain fields data (can be empty/null).
• custom_properties (optional). Gets or Sets custom properties (This includes details for Server Initiated Connection feature)
• hidden (optional). Whether to hide the application.
• agentlessAccess (optional). Agentless Access.
• destination (optional). This field is required when creating ZTNA applications.
  • destination. Destination value must be one of the following hostname, ip-range, and ip.
  • port. Port Number for the client-server app.
  • protocol. Protocol for the client-server app. Takes one of PROTOCOL_TCP and PROTOCOL_UDP values.
  • subtype. Protocol for the client-server app. Takes one of SUBTYPE_HOSTNAME, SUBTYPE_IP_AND_CIDR and SUBTYPE_IP_RANGE values.
• policyCount (optional). Contextual policy count associated with the application.
• createdTime (optional). Application created time.
• relatedURLs (optional). Graph related URLs. This field is required when creating non-ZTNA (secure) applications.
• icon. Base64 encoded icon data.
• usingTemplate. A boolean true or false indicating whether this application uses a template or not. This field is required when creating non-ZTNA (secure) applications.
• templateName. The template name, if one is used.
• id (read only). The ID of the application.

1. Get list of applications

The following is an example of a GET request and response for getting a list of applications:

GET https://{ hostUrl }:{ port }/accessSecurity/applications

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request parameters

A set of optional parameters can be used in the GET request:

A sample URL:

GET https://{ hostUrl }:{ port }/accessSecurity/applications?offset=0limit=3&orderby=name&type=saas&name=TestApplication

This API invocation requests the first three SAAS applications from the collection of applications that contain TestApplication in their name and are ordered by their name.

Successful response sample

A 200 OK response with a JSON body:

{
    "items": [
        {
            ...Application #1...
        },
        {
            ...Application #2...
        },
        {
            ...Application #3...
        }
    ],
    "totalNum": 10
}
<!--NeedCopy-->

The JSON object has an items array that contains the list of application objects. The list can be whole or partial depending on the pagination parameters used (offset, limit). The JSON object also has a totalNum property that contains the total number of application objects that would be returned regardless of the pagination parameters.

Potential unsuccessful responses

2. Get specific application

The following is an example of a GET request and response for getting a specific application. The application’s UUID is appended to the request URL:

GET https://{ hostUrl }:{ port }/accessSecurity/applications/{ applicationUUID }

Request header sample

...
Accept: application/json
Authorization: bearer \{\{bearerToken\}\}
...
<!--NeedCopy-->

Successful response sample

A 200 OK response with a JSON body that contains an application object:

Response body sample

{
    "id" : "Z5xd0s",
    "name" : "TestApp",
    "type" : "saas",
    "description" : " ",
    "category" : null,
    "keywords" : [],
    "url" : "https://sample.com",
    "hidden" : false,
    "destination" : [],
    "state" : "complete",
    "relatedURLs" : ["*.sample.com"],
    "icon" :"data:image/x-icon;base64,iVBORw0KGgoAA1/5 . . . CYII=",
    "policyCount" : 0,
    "custom_properties" : {
        "sic_app_details": {
            "clients": [],
            "backend_servers": []
         }
    },
    "createdTime" : "2024-10-21T13:49:25Z", 
    "templateName"  : null,
    "usingTemplate"  : null,
    "sbsOnlyLaunch"  : null,
    "mobileSecurity"  : null,
    "customerDomainFields"  : null,
    "sso"  : null
}
<!--NeedCopy-->

Potential unsuccessful responses

3. Get all policies bound to a specific application

The following is an example of a GET request and response for getting all policies bound to a specific application. The application’s UUID is used to the request URL:

GET https://{ hostUrl }:{ port }/accessSecurity/applications/{ applicationUUID }/policies

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
Citrix-TransactionId: { Citrix-TransactionId }
...
<!--NeedCopy-->

Successful response sample

A 200 OK response with body:

[
    {
        "policy_xid":["xH2DAi"],
        "name":["TestPolicy1"]
     },
     {
        "policy_xid":["Ly5P8s"],
        "name":["TestPolicy2"]
     }
]
<!--NeedCopy-->

Potential Unsuccessful Responses

4. Create application

The following is an example of a POST request and response for creating a new application:

POST https://{ hostUrl }:{ port }/accessSecurity/applications

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request body sample for non-ZTNA applications

{
	"agentlessAccess": false,
	"category": null,
	"customerDomainFields": null,
	"description": " ",
	"hidden": false,
	"icon": "data:image/x-icon;base64,AAABAAAAA=",
	"keywords": null,
	"name": "AnotherApp",
	"relatedURLs": [
		"*.simple.com"
	],
	"templateName": "",
	"type": "web",
	"url": "https://www.simple.com",
	"usingTemplate": false
}
<!--NeedCopy-->

Request body sample for ZTNA applications

{
    "agentlessAccess": false,
    "category": null,
    "description": "Test Description",
    "destination": [{"destination": "10.78.2.23", "port": "22", "protocol": "PROTOCOL_TCP", "subtype": "SUBTYPE_IP_AND_CIDR"}],
    "hidden": false,
    "icon": "K5CYII=",
    "name": "tcp_a}pp",
    "type": "ztna"
}
<!--NeedCopy-->

Response body sample for non-ZTNA applications

{
	"id": "R4ThlN",
	"name": "AnotherApp",
	"type": "web",
	"description": " ",
	"category": null,
	"keywords": [],
	"url": "https://www.simple.com",
	"hidden": false,
	"destination": [],
	"state": "complete",
	"relatedURLs": [
		"*.simple.com"
	],
	"icon": "data:image/x-icon;base64,AAABAAEAlpYAAAEAIABwawEAFgAAACgAAAAA=",
	"policyCount": 0,
	"custom_properties": {
		"sic_app_details": {
			"clients": [],
			"backend_servers": []
		}
	},
	"createdTime": "2024-12-12T13:34:23Z",
	"templateName": null,
	"usingTemplate": null,
	"sbsOnlyLaunch": null,
	"mobileSecurity": null,
	"customerDomainFields": null,
	"sso": null
}
<!--NeedCopy-->

Response body sample for ZTNA applications

{
    "id": "cBmiFA",
    "name": "tcpApp",
    "type": "ztna",
    "description": "Test Description",
    "category": null,
    "keywords": [],
    "url": "",
    "hidden": false,
    "destination": [
        {
            "id": "1",
            "destination": "10.78.2.23",
            "port": "22",
            "protocol": "PROTOCOL_TCP",
            "subtype": "SUBTYPE_IP_AND_CIDR",
            "routingType": "internal"
        }
    ],
    "state": "complete",
    "relatedURLs": [],
    "icon": "AAA=",
    "policyCount": 0,
    "custom_properties": {
        "sic_app_details": {
            "clients": [],
            "backend_servers": []
        }
    },
    "createdTime": "2024-12-13T13:07:33Z",
    "templateName": null,
    "usingTemplate": null,
    "sbsOnlyLaunch": null,
    "mobileSecurity": null,
    "customerDomainFields": null,
    "sso": null
}
<!--NeedCopy-->

Successful response sample

An empty 201 Created response.

Potential unsuccessful responses

5. Update application

The following is an example of a PUT request and response for Updating a specific application. The application’s UUID is appended to the request URL:

PUT https://{ hostUrl }:{ port }/accessSecurity/applications/{ applicationUUID }

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: bearer { bearerToken }
...
<!--NeedCopy-->

Request body sample

The following is an example of editing the name of the application. A standard JSON is used to modify the element that was edited, the name in this case.

{
    "agentlessAccess": false,
    "category": null,
    "description": " ",
    "destination": [{"destination": "10.78.2.23", "port": "22", "protocol": "PROTOCOL_TCP", "subtype": "SUBTYPE_IP_AND_CIDR"}],
    "hidden": false,
    "icon": "K5CYII=",
    "name": "tcp_app",
    "type": "ztna",
    "id": "nysCLV"
}
<!--NeedCopy-->

Successful response sample

A 204 NO CONTENT response with an empty body.

Potential unsuccessful responses

6. Delete application

The following is an example of a DELETE request and response for deleting a specific application. The application’s UUID is appended to the request URL:

DELETE https://{ hostUrl }:{ port }/accessSecurity/applications/{ applicationUUID }

Request header sample

...
Accept: application/json
Authorization: bearer { bearerToken }
Citrix-TransactionId: { Citrix-TransactionId }
...
<!--NeedCopy-->

Successful response sample

A 204 NO CONTENT response with an empty body.

Potential Unsuccessful Responses