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 1
Create 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 Key
and 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
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
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
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
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:
Related Information