Access Security

Handling applications with Secure Private Access APIs

December 21, 2023

Contributed by:

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.

1. Get list of applications

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

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

Request header sample

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

Request parameters

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

Parameter Name	Parameter Type	Parameter Description
offset	Positive Integer	Starting index of the returned collection. Default is 0.
limit	Positive Integer	Max index of the last returned item for this request. It must always be offset < limit. Default is 1000.
orderby	String	The field used to sort the returned list. Fields that can be used with `orderby` are `name`, `type`, `category` and other.
name	String	A string used to search for applications with this exact `name` field.
type	String	A string used to search for ZTNA applications with this exact `type` field. The field that can be used is `ztna`.

A sample URL:

GET https://api.cloud.com/accessSecurity/applications?offset=0limit=3&orderby=name&type=ztna&name=TestApplication

This request asks for the first to third ZTNA applications (3 items total) from the collection of applications that are named TestApplication and are ordered by name field.

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.

Applications object schema in response body

Each application object in the items array contains the following schema. 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.
locations (optional).
- name. Resource location name.
- uuid. Resource location UUID.
url (optional). Application URL. This field is required when creating non-ZTNA (secure) applications.
policies. Policies of this application.
- type. Takes one of patterns and capability values.
- data. JSON object containing policy capability data (can be empty/null)
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).
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.
iconURL (optional). The icon URL.
sso (optional). Single sign-on. The SSO value must be one of the following; none, basic, saml, kerberos, form, and nosso.
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.

Potential unsuccessful responses

Status Code - Description	Potential Reason
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.

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://api.cloud.com/accessSecurity/applications/{{applicationUUID}}`

Request header sample

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

Successful response sample

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

Response body sample

{
    "state": "incomplete",
    "usingTemplate": true,
    "templateName": "Test Template",
    "name": "Test",
    "type": "web",
    "description": "Test Description",
    "category": "Test Category",
    "locations": [
        {
            "name": "testname",
            "uuid": "1111-1111-1111-1111"
        }
    ],
    "url": "https://sample.com",
    "policies": [],
    "sbsOnlyLaunch": true,
    "mobileSecurity": true,
    "customerDomainFields": {},
    "hidden": false,
    "agentlessAccess": true,
    "destination": [],
    "policyCount": null,
    "createdTime": "2023-01-19T10:00:22Z",
    "relatedURLs": [
        "www.test.com"
    ],
    "icon": "iVBORw0KGg5CYII=",
    "iconURL": "",
    "sso": null,
    "id": "b20788e2-cdf0-490e-adac-5b100271ad3d"
}
<!--NeedCopy-->

JSON object schema in response body

Each property value is given as a string unless differently specified.

state (optional). State of the application. Takes one of incomplete and complete values.
icon. Base64 encoded icon data.
iconURL (optional). The icon URL.
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.
locations (optional).
- name. Resource location name.
- uuid. Resource location UUID.
url (optional). Application URL. This field is required when creating non-ZTNA (secure) applications.
policies. Policies of this application.
- type. Takes one of patterns and capability values.
- data. JSON object containing policy capability data (can be empty/null)
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).
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.
iconURL (optional). The icon URL.
sso (optional). Single sign on. The SSO value must be one of the following none, basic, saml, kerberos, form, and nosso.
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.

Potential unsuccessful responses

Status Code - Description	Potential Reason
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
404 NOT FOUND	No application was found with the specified UUID.

3. Create application

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

POST https://api.cloud.com/accessSecurity/applications

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Citrix-CustomerId: \{\{customerId\}\}
Authorization: CWSAuth Bearer=\{\{bearerToken\}\}
Citrix-TransactionId: \{\{Citrix-TransactionId\}\}
...
<!--NeedCopy-->

Request body sample for non-ZTNA applications

{
  "name": "Test",
  "type": "web",
  "description": "Test Description",
  "category": "Test Category",
  "locations": [
    {
      "name": "testname",
      "uuid": "1111-1111-1111-1111"
    }
  ],
  "url": "https://sample.com",
  "policies": [
    {
      "type": "patterns",
      "data": {}
    }
  ],
  "sbsOnlyLaunch": true,
  "mobileSecurity": true,
  "customerDomainFields": {},
  "hidden": false,
  "agentlessAccess": true,
  "destination": [],
  "policyCount": "Test Count",
  "createdTime": {},
  "relatedURLs": ["www.test.com"],
  "icon": "SXQgY2Fubm90IGJlIWdodGVyLgo=",
  "iconURL": "iconurl.com",
  "sso": {},
  "usingTemplate": true,
  "templateName": "Test Template"
}
<!--NeedCopy-->

Request body sample for ZTNA applications

{
  "name": "Test",
  "type": "ztna",
  "description": "Test Description",
  "category": "Test Category",
  "locations": [
    {
      "name": "testname",
      "uuid": "1111-1111-1111-1111"
    }
  ],
  "policies": [
    {
      "type": "patterns",
      "data": {}
    }
  ],
  "sbsOnlyLaunch": true,
  "mobileSecurity": true,
  "customerDomainFields": {},
  "hidden": false,
  "agentlessAccess": false,
  "destination": [
    {
      "destination": "string",
      "port": "65",
      "protocol": "PROTOCOL_TCP",
      "subtype": "SUBTYPE_HOSTNAME"
    }
  ],
  "policyCount": "Test Count",
  "createdTime": {},
  "icon": "SXQgY2Fubm90IGJlIWdodGVyLgo",
  "iconURL": "iconurl.com",
  "sso": {}
}
<!--NeedCopy-->

JSON object schema in request body

Each property value is given as a string unless differently specified.

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.
locations (optional).
- name. Resource location name.
- uuid. Resource location UUID.
url (optional). Application URL. This field is required when creating non-ZTNA (secure) applications.
policies. Policies of this application.
- type. Takes one of patterns and capability values.
- data. JSON object containing policy capability data (can be empty/null)
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).
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.
iconURL (optional). The icon URL.
sso (optional). Single sign-on. The SSO value must be one of the following none, basic, saml, kerberos, form, and nosso.
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.

Response body sample for non-ZTNA applications

{
    "state": "incomplete",
    "usingTemplate": true,
    "templateName": "Test Template",
    "name": "Test",
    "type": "web",
    "description": "Test Description",
    "category": "Test Category",
    "locations": [
        {
            "name": "testname",
            "uuid": "1111-1111-1111-1111"
        }
    ],
    "url": "https://sample.com",
    "policies": [],
    "sbsOnlyLaunch": true,
    "mobileSecurity": true,
    "customerDomainFields": {},
    "hidden": false,
    "agentlessAccess": true,
    "destination": [],
    "policyCount": null,
    "createdTime": "2023-01-18T14:43:17Z",
    "relatedURLs": [
        "www.test.com"
    ],
    "icon": "iVBORw0KGg5CYII=",
    "iconURL": "iconurl.com",
    "sso": null,
    "id": "b20788e2-cdf0-490e-adac-5b100271ad3d"
}
<!--NeedCopy-->

Response body sample for ZTNA applications

{
    "state": "incomplete",
    "icon": "iVBOAASUVORK5CYII=",
    "iconURL": "",
    "name": "Test",
    "type": "ztna",
    "description": "Test Description",
    "locations": [
        {
            "name": "testname",
            "uuid": "1111-1111-1111-1111"
        }
    ],
    "destination": [
        {
            "destination": "string",
            "port": "65",
            "protocol": "PROTOCOL_TCP",
            "subtype": "SUBTYPE_HOSTNAME"
        }
    ],
    "id": "7311b7f1-5aae-4bcd-8066-c603dbec01ee"
}
<!--NeedCopy-->

JSON object schema in response body

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.
locations (optional).
- name. Resource location name.
- uuid. Resource location UUID.
url (optional). Application URL. This field is required when creating non-ZTNA (secure) applications.
policies. Policies of this application.
- type. Takes one of patterns and capability values.
- data. JSON object containing policy capability data (can be empty/null)
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).
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.
iconURL (optional). The icon URL.
sso (optional). Single sign on. The SSO value must be one of the following none, basic, saml, kerberos, form, and nosso.
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.

Successful response sample

An empty 201 Created response.

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	An invalid JSON in the request body.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
415 UNSUPPORTED MEDIA TYPE	`Content-Type` header not set as `application/json; charset=utf-8`.

4. 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://api.cloud.com/accessSecurity/applications/{{applicationUUID}}`

Request header sample

...
Accept: application/json
Content-Type: application/json; charset=utf-8
Citrix-CustomerId: \{\{customerId\}\}
Authorization: CWSAuth Bearer=\{\{bearerToken\}\}
Citrix-TransactionId: \{\{Citrix-TransactionId\}\}
...
<!--NeedCopy-->

Request body sample

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

{
  "name": "Test",
  "type": "ztna",
  "description": "Test Description",
  "category": "Test Category",
  "locations": [
    {
      "name": "testname",
      "uuid": "1111-1111-1111-1111"
    }
  ],
  "policies": [
    {
      "type": "patterns",
      "data": {}
    }
  ],
  "sbsOnlyLaunch": false,
  "mobileSecurity": true,
  "customerDomainFields": {},
  "hidden": false,
  "agentlessAccess": false,
  "destination": [
    {
      "destination": "string",
      "port": "65",
      "protocol": "PROTOCOL_TCP",
      "subtype": "SUBTYPE_HOSTNAME"
    }
  ],
  "policyCount": "Test Count",
  "createdTime": {},
  "icon": "SXQgY2Fubm90IGJlIWdodGVyLgo",
  "iconURL": "iconurl.com",
  "sso": {}
}
<!--NeedCopy-->

Successful response sample

A 204 NO CONTENT response with an empty body.

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	An invalid JSON in the request body.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in the headers.
404 NOT FOUND	No policy was found with the specified UUID.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
409 CONFLICT	Icon already in use. Returns an application object that is using the icon.
415 UNSUPPORTED MEDIA TYPE	`Content-Type` header not set as `application/json; charset=utf-8`.

5. 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://api.cloud.com/accessSecurity/applications/{{applicationUUID}}`

Request header sample

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

Successful response sample

A 204 NO CONTENT response with an empty body.

Potential Unsuccessful Responses

Status Code - Description	Potential Reason
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
404 NOT FOUND	No policy was found with the specified UUID.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.

Note: For detailed information on the SSO, see Citrix Secure Private Access single sign-on for web apps and Support for Enterprise web apps.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Resources

Access Security OpenAPI Specification

Copy Download

Handling applications with Secure Private Access APIs

December 21, 2023

Contributed by:

December 21, 2023

Contributed by:

Handling applications with Secure Private Access APIs

1. Get list of applications

Request header sample

Request parameters

Successful response sample

Applications object schema in response body

Potential unsuccessful responses

2. Get specific application

Request header sample

Successful response sample

Response body sample

JSON object schema in response body

Potential unsuccessful responses

3. Create application

Request header sample

Request body sample for non-ZTNA applications

Request body sample for ZTNA applications

JSON object schema in request body

Response body sample for non-ZTNA applications

Response body sample for ZTNA applications

JSON object schema in response body

Successful response sample

Potential unsuccessful responses

4. Update application

Request header sample

Request body sample

Successful response sample

Potential unsuccessful responses

5. Delete application

Request header sample

Successful response sample

Potential Unsuccessful Responses

Resources

Access Security OpenAPI Specification

In this article

Resources

Access Security OpenAPI Specification