Cisco Secure Access Destination Lists, Destinations

Destination Lists

The Cisco Secure Access Destination Lists API enables you to create and manage access to network destinations. You can block or allow a destination on your policy access rules in Secure Access.

Overview

About Destination Lists

  • Create a destination list and add a list of destinations
  • Get, update, and delete a destination list
  • Find the destination lists

About Destinations

  • Add destinations to a destination list
  • Find the destinations in a destination list
  • Delete the destinations in a destination list

You can find the Destination Lists API endpoints under the policies scope in the Secure Access API.

Types of Destination

A destination represents the following types of network location identifier:

  • Fully qualified domain name (FQDN)
  • URL
  • IPv4 or IPv6 address

You can create destination lists and add the various types of destination to a destination list.

Walkthrough: Secure Access Destination Lists API

Rate Limits for Destination Lists and Destinations

Secure Access enables rate limits on the Destination Lists and Destination API endpoints. For more information, see Rate Limits > Destination Lists and Destinations.

Request Headers

Unless specified, the Secure Access API endpoints use JSON for all requests and responses.

Note: For POST, PUT, and PATCH operations, set the HTTP Content-Type header to application/json in your API request.

POST Requests and Destination Limits

The Destination Lists API POST endpoints accept no more than 500 Destination objects in the body of the request.

Note: You cannot use the Destination Lists API to create a destination list with the access type of thirdparty_block. Secure Access creates destination lists with the thirdparty_block access type for the integration of the third-party and custom security vendors with threat feeds.

  • POST https://api.sse.cisco.com/policies/v2/destinationlists
  • POST https://api.sse.cisco.com/policies/v2/destinationlists/{destinationListId}/destinations

Note: If you make an API request to create a Destination List with more than 500 Destination objects, Secure Access returns an HTTP 400 error response.

Error Conditions When Adding URLs on High-Volume Domains to Destination Lists

If you make a Destination Lists API request that adds a URL on a high-volume domain to a destination list, the operation may succeed (HTTP/200 OK). However, the server returns an error message (HTTP/400 Bad Request) that indicates that the destination is on a high-volume domain.

Note: Secure Access does not add URLs on high-volume domains to destination lists. Instead, we recommend that you add the domain only.

For more information about the error conditions that may occur when you add destinations to destination lists, see Secure Access Help: Troubleshooting Destination Lists.

Global Access Lists

Secure Access does not support global destination lists. When you create a destination list, set the isGlobal field to false.

Bundle Types

  • When you create a destination list, set the bundleTypeId field to 2. Secure Access supports the value of 2 (Web profile) for the bundle type (bundleTypeId).
  • Secure Access creates destination lists with the thirdparty_block access type and the bundleTypeId of 1.

Access Type

Secure Access does not support an access type on destination lists. When you create a destination list, set the access field to none.

Delete Destinations and Destination Limits

The Destination Lists API DELETE operation, that removes a list of destinations from a destination list, accepts no more than 500 destination IDs in the body of the API request.

  • DELETE https://api.sse.cisco.com/policies/v2/destinationlists/{destinationListId}/destinations/remove

Note: If you make an API request to remove more than 500 destinations from a destination list, Secure Access returns an HTTP 400 error response.

Total Pages in Destination Lists API Collections

You can use the value of the total field from the meta object in the API response to calculate the total number of pages in a collection of destination lists or destinations.

Note: For the Destination Lists API endpoints that return a collection, the default value for the page query parameter is 1. The default value for the limit query parameter is 100.

Destination Lists API endpoints that accept the limit and query parameters:

  • GET https://api.sse.cisco.com/policies/v2/destinationlists
  • GET https://api.sse.cisco.com/policies/v2/destinationlists/{destinationListId}/destinations

Query Destination Lists Collection for Total Records

Create a GET request to the Destination Lists API collection, and set the page parameter to a number that you estimate is larger than the number of pages in the collection.

Example Request:

curl -L --location-trusted --request GET --url 'https://api.sse.cisco.com/policies/v2/destinationlists?page=50&limit=1' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Example Response:

{
    "status": {
        "code": 200,
        "text": "OK"
    },
    "meta": {
        "page": 50,
        "limit": 1,
        "total": 2
    },
    "data": []
}

Calculate Total Pages in Collection

After getting the total number of records in the collection, calculate the number of pages in the collection. For a collection with more than the default number of records in a page (100), divide the total number of records by the default number of records in a page. If the total number of records in the collection is less than the default number of records in a page, the number of pages in the collection is 1.

Destination Lists API Endpoints