Access Security

Handling application domains with Secure Private Access API

December 21, 2023

Contributed by:

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

1. Get list of application domains

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

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

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 `fqdn`, `type`, `flag`, `error`, `comment`, `appType`, and `ip`.
status	Boolean	Fetch status of routing domains instead of full list.

A sample URL:

GET https://api.cloud.com/accessSecurity/routingDomains?status=true&offset=10&limit=20&orderby=fqdn

This request asks for the tenth to twentieth items (11 items total) from the collection of application domains whose status is false and are ordered by the fqdn field.

Successful response sample with status parameter false

A 200 OK response with a JSON body:

{
    "id": null,
    "status": {
        "statusCode": 0,
        "statusText": "Status OK",
        "errCount": 0
    },
    "items": [
        {
            ...Application Domain #1...
        },
        {
            ...Application Domain #2...
        },
        {
           ...Application Domain #3...
        }
    ]
}
<!--NeedCopy-->

The JSON object has an id element. The JSON object also has a status property that contains statusCode, statusText, and errCount. Also, the JSON object has an items property that contains all the routing domains.

Application domains object schema in response body with status parameter value false

Each application domain object in the items array contains the following schema. Each property value is given as a string unless differently specified.

id. The Routing Domain identifier (unique).
status. The routing entry status.
- statusCode. The status code.
- statusText. The status description.
- errCount. The number of errors.
items. The list with the routing domains.
- fqdn. The FQDN which must be routed. Max domain length 255 characters.
- type. Type of routing entry. Fields that can be used are internal, external, external_via_connector, and conflicting.
- flag. Routing entry is enabled or disabled. The default value is enabled.
- locationIds. List of resource location UUIDs.
- error. Any error associated with this routing entry. The default value is none.
- comment. Admin to add some description to a routing entry. Max comment length 64 characters.
- appType (optional). The type of app binding to this routing entry.
- ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Successful response sample with status parameter value true

A 206 Partial Content response with a JSON body:

{
    "status": {
        "statusCode": 0,
        "statusText": "Status OK",
        "errCount": 0
    }
}
<!--NeedCopy-->

The JSON object also has a status property that contains statusCode, statusText, and errCount.

Application domains object schema in response body

Each application domain object in the items array contains the following schema. Each property value is given as a string unless differently specified.

status. The routing entry status.
- statusCode. The status code.
- statusText. The status description.
- errCount. The number of errors.

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	A parameter was not given by the correct type. The JSON object in the response body usually provides enough information about the error.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

2. Get a specific application domain

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

GET https://api.cloud.com/accessSecurity/routingDomains/{{applicationDomain}}`

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 domain object:

{
    "flag": "disabled",
    "fqdn": "test.com",
    "appType": "",
    "ip": false,
    "locationIds": [],
    "comment": "this is a test",
    "type": "external",
    "error": "none"
}
<!--NeedCopy-->

JSON object schema in response body

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

fqdn. The fqdn which must be routed. Max domain length 255 characters.
type. Type of routing entry. Fields that can be used are internal, external, external_via_connector, and conflicting.
flag. Routing entry is enabled or disabled. The default value is enabled.
locationIds. List of resource location UUIDs.
error. Any error associated with this routing entry. The default value is none.
comment. Admin to add some description to a routing entry. Max comment length 64 characters.
appType (optional). The type of app binding to this routing entry.
ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Potential unsuccessful responses

Status Code - Description	Potential Reason
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in the headers.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
404 NOT FOUND	No application domain with this name found.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

3. Create application domain

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

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

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

{
    "fqdn": "www.testrouting.com",
    "type": "external",
    "flag": "enabled",
    "locationIds": [],
    "error": "none",
    "comment": "",
    "appType": "",
    "ip": false
}
<!--NeedCopy-->

JSON object schema in request body

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

fqdn. The fqdn which must be routed. Max domain length 255 characters.
type. Type of routing entry. Fields that can be used are internal, external, external_via_connector, and conflicting.
flag. Routing entry is enabled or disabled. The default value is enabled.
locationIds. List of resource location UUIDs.
error. Any error associated with this routing entry. The default value is none.
comment. Admin to add some description to a routing entry. Max comment length 64 characters.
appType (optional). The type of app binding to this routing entry.
ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Successful response sample

A 201 CREATED response with a JSON body:

{
    "fqdn": "www.testrouting.com",
    "type": "external",
    "flag": "enabled",
    "locationIds": [],
    "error": "none",
    "comment": "",
    "appType": "",
    "ip": false
}
<!--NeedCopy-->

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	JSON object sent in the request body might not follow the correct schema. The JSON object in the response body usually provides enough information about such a mistake.
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`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

4. Update application domain

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

PUT https://api.cloud.com/accessSecurity/routingDomains/{{applicationDomain}}`

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

{
    "fqdn": "www.testrouting.com",
    "type": "external",
    "flag": "enabled",
    "locationIds": [],
    "error": "none",
    "comment": "",
    "appType": "",
    "ip": false
}
<!--NeedCopy-->

JSON object schema in request body

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

fqdn. The FQDN which must be routed. Max domain length 255 characters.
type. Type of routing entry. Fields that can be used are internal, external, external_via_connector, and conflicting.
flag. Routing entry is enabled or disabled. The default value is enabled.
locationIds. List of resource location UUIDs.
error. Any error associated with this routing entry. The default value is none.
comment. Admin to add some description to a routing entry. Max comment length 64 characters.
appType (optional). The type of app binding to this routing entry.
ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Successful response sample

A 200 OK response with a JSON body:

{
    "fqdn": "www.testrouting.com",
    "type": "external",
    "flag": "enabled",
    "locationIds": [],
    "error": "none",
    "comment": "",
    "appType": "",
    "ip": false
}
<!--NeedCopy-->

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	JSON object sent in the request body might not follow the correct schema. The JSON object in the response body usually provides enough information about such a mistake.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in headers.
404 NOT FOUND	No application domain with this name found.
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`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

5. Delete application domain

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

DELETE https://api.cloud.com/accessSecurity/routingDomains/{{applicationDomain}}`

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
400 BAD REQUEST	A Request error occurred.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in the headers.
404 NOT FOUND	No application domain with this name found.
406 NOT ACCEPTABLE	`Accept` header not set as `application/json`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

6. Reset all application domains

The following is an example of a POST request and response for resetting all the application domains:

POST https://api.cloud.com/accessSecurity/routingDomains/reset

Request header sample

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

Successful response sample

A 201 CREATED response with a JSON body:

{
    "id": null,
    "status": {
        "statusCode": 0,
        "statusText": "Status OK",
        "errCount": 0
    },
    "items": [
        {
            ...Application Domain #1...
        },
        {
            ...Application Domain #2...
        },
        {
           ...Application Domain #3...
        }
    ]
}
<!--NeedCopy-->

Application domains object schema in response body

Each application domain object in the items array contains the following schema. Each property value is given as a string unless differently specified.

id. The routing domain identifier (unique).
status. The Routing Entry Status.
- statusCode. The status code.
- statusText. The status description.
- errCount. The number of errors.
items. The list with the routing domains.
- fqdn. The FQDN which must be routed. Max domain length 255 characters.
- type. Type of routing entry. Fields that can be used are internal, external, external\_via\_connector, and conflicting.
- flag. Routing entry is enabled or disabled. The default value is enabled.
- locationIds. List of resource location UUIDs.
- error. Any error associated with this routing entry. The default value is none.
- comment. Admin to add some description to a routing entry. Max comment length 64 characters.
- appType (optional). The type of app binding to this routing entry.
- ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Potential unsuccessful responses

Status Code - Description	Potential Reason
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in the 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`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

7. Search for application domains

The following is an example of a POST request and response for search application domains:

POST https://api.cloud.com/accessSecurity/routingDomains/search

Request header sample

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

Request body sample

{
    "fqdnList": ["www.testrouting1.com", "www.testrouting2.com", "www.testrouting3.com"]
}
<!--NeedCopy-->

JSON Object schema in request body

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

fqdnList. The list of FQDNs to search.

Successful response sample

A 200 OK response with a JSON body:

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

The property items contains all the found routing domains requested from the fqdnList.

Application domains object schema in response body

Each application domain object in the items array contains the following schema. Each property value is given as a string unless differently specified.

items. The list with the routing domains.
- fqdn. The FQDN which must be routed. Max domain length 255 characters.
- type. Type of routing entry. Fields that can be used are internal, external, external\_via\_connector, and conflicting.
- flag. Routing entry is enabled or disabled. The default value is enabled.
- locationIds. List of resource location UUIDs.
- error. Any error associated with this routing entry. The default value is none.
- comment. Admin to add some description to a routing entry. Max comment length 64 characters.
- appType (optional). The type of app binding to this routing entry.
- ip (optional). A boolean variable. Whether the secure access app has IP address-based configuration. The default value is False.

Potential unsuccessful responses

Status Code - Description	Potential Reason
400 BAD REQUEST	A Request error occurred.
401 UNAUTHORIZED	An invalid `CitrixId` or `Authorization` token in the 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`.
500 INTERNAL SERVER ERROR	Some other form of catastrophic error.

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 application domains with Secure Private Access API

December 21, 2023

Contributed by:

December 21, 2023

Contributed by:

Handling application domains with Secure Private Access API

1. Get list of application domains

Request header sample

Request parameters

Successful response sample with status parameter false

Application domains object schema in response body with status parameter value false

Successful response sample with status parameter value true

Application domains object schema in response body

Potential unsuccessful responses

2. Get a specific application domain

Request header sample

Successful response sample

JSON object schema in response body

Potential unsuccessful responses

3. Create application domain

Request header sample

Request body sample

JSON object schema in request body

Successful response sample

Potential unsuccessful responses

4. Update application domain

Request header sample

Request body sample

JSON object schema in request body

Successful response sample

Potential unsuccessful responses

5. Delete application domain

Request header sample

Successful response sample

Potential unsuccessful responses

6. Reset all application domains

Request header sample

Successful response sample

Application domains object schema in response body

Potential unsuccessful responses

7. Search for application domains

Request header sample

Request body sample

JSON Object schema in request body

Successful response sample

Application domains object schema in response body

Potential unsuccessful responses

Resources

Access Security OpenAPI Specification

In this article

Resources

Access Security OpenAPI Specification