Manage Destination Lists via Curl with Secure Access API

Introduction

This document describes how to manage destination lists via curl with Secure Access API.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Secure Access
• Secure Access API
• curl
• Json

Components Used

The information in this document is based on these software and hardware versions:

• Secure Access
• Secure Access APIs
• curl
• Json

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Configure

1.Create your API key 

Navigate to Secure Access Dashboard.

• Click on Admin > Api Keys > Add


Create your API Key 1Create your API Key 2

• Add desired API Key Name , Description (Optional) , Expiry Date as required

Create your API Key 3

• Under Key Scope, chose Policies then Expand policies 
• Chose Destination Lists  and Destinations
• Change Scope if required, otherwise keep as Read/Write
• Click on CREATE KEY

Create your API Key 4

• Copy the API Keyand the Key Secret and then click on ACCEPT AND CLOSE

Create your API Key 5

Note: There is only one opportunity to copy your API secret. Secure Access does not save your API secret and you cannot retrieve it after its initial creation.

2.Generate an API Access Token

In order to generate the API Access Token, make a Token Authorization Request:

Token Authorization Request

Use the Secure Access API credentials that you created for your organization to generate an API access token.

• In the curl sample, substitute your Secure Access API key and secret

curl --user key:secret --request POST --url https://api.sse.cisco.com/auth/v2/token -H Content-Type: application/x-www-form-urlencoded -d grant_type=client_credentials

• Copy and save the generated Bearer API Token

Note: A Secure Access OAuth 2.0 access token expires in one hour (3600 seconds). It is recommend that you do not refresh an access token until the token is nearly expired.

3.Manage Destination Lists

There are multiple ways to manage destination lists which include:

Get all Destination Lists

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request GET --url https://api.sse.cisco.com/policies/v2/destinationlists -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json"

Snippet from sample output:

{"id":23456789,"organizationId":1234567,"access":"none","isGlobal":false,"name":" Test Block list","thirdpartyCategoryId":null,"createdAt":1694070823,"modifiedAt":1702819637,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":2,"meta":
{"destinationCount":2,"domainCount":2,"urlCount":0,"ipv4Count":0,"applicationCount":0}

Make a note of the destinationListId which is listed under "id" field of the output which is used further for GET, POST or DELETE requests specific to this destination list.

Get all destinations within a Destination List

• Get the destinationListId using this earlier mention step, Get all Destination Lists

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request GET --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId/destinations -H "Authorization: Bearer YourAccessToken" 

 Sample Output:

{"status":{"code":200,"text":"OK"},"meta":{"page":1,"limit":100,"total":3},"data":
[
{"id":"415214","destination":"cisco.com","type":"domain","comment":null,"createdAt":"2024-02-20 09:15:46"},{"id":"7237895","destination":"www.cisco.com","type":"domain","comment":null,"createdAt":"2024-02-20 10:19:51"},{"id":"29275814","destination":"10.10.10.10","type":"ipv4","comment":null,"createdAt":"2024-02-20 09:15:46"},{"id":"71918495","destination":"www.subdomain.cisco.com/resoucre","type":"url","comment":null,"createdAt":"2024-02-20 10:29:02"}
]}

Create a new Destination List

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request POST --url https://api.sse.cisco.com/policies/v2/destinationlists -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -H "Accept: application/json" -d "{\"access\":\"none\",\"isGlobal\":false,\"name\":\"Destination List Name\"}"

Note: Replace 'Destination List Name' with the desired name.

Sample Output:

{"id":23456789,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708417690,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta":{"destinationCount":0}}

Add destinations to a Destination List

• Get the destinationListId using this earlier mention step, Get all Destination Lists

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request POST --url https://api.sse.cisco.com/policies/v2/destinationlists/{destinationListId}/destinations -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -d "[{\"destination":"cisco.com\"},{\"destination\":\"10.10.10.10\"},{\"destination\":\"www.subdomain.cisco.com\/resource\"}]"

Sample Output:

{"status":{"code":200,"text":"OK"},"data":{"id":17804929,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708420546,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta":
{"destinationCount":3}}}

Delete a Destination List

• Get the destinationListId using this earlier mention step, Get all Destination Lists

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request DELETE --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId -H "Authorization: Bearer YourAccessToken"​

Sample Output:

{"status":{"code":200,"text":"OK"},"data":[]}

Delete destinations from a Destination List

• Get the destinationListId using this earlier mention step, Get all Destination Lists
• Get the id of the particular destination within the list which needs to be deleted using this earlier mentioned step, Get all destinations within a destination list

Open windows command prompt or Mac terminal to run the command:

curl -L --location-trusted --request DELETE --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId/destinations/remove -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -H "Accept: application/json" -d "[id1,id2]"

Sample Output:

{"status":{"code":200,"text":"OK"},"data":{"id":17804929,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708525645,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta":{"destinationCount":2}}}

Troubleshoot

The Secure Access API endpoints use HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate server errors. The approach to resolve the issue would depend on the response code that is received:

REST API - Response codes 1

REST API - Response codes 2Additionally while troubleshooting API related errors or problems, here are the Rate Limits to be aware of:

• Secure Access API Limits

Related Information

• Cisco Secure Access User Guide
• Cisco Technical Support and Downloads
• Add Secure Access API Keys
• Developers User Guide