Application Lists API Guide
This guide provides Python client samples for the Cisco Secure Access Application Lists API.
Note: Your Secure Access API key must have the permissions to read and write on thepoliciesandreportskey scopes. For more information about the API key scopes, see Secure Access OAuth 2.0 Scopes.
First get your Secure Access API key, set up your environment, and install the Secure Access API client. For more information, see Samples Overview.
Run the Script
- Copy the script to a local file called
main.py. Locate the script in your environment in a directory above theciscodirectory. - Run
python3 main.py.
main.py
"""
Copyright (c) 2025 Cisco and/or its affiliates.
This software is licensed to you under the terms of the Cisco Sample
Code License, Version 1.1 (the "License"). You may obtain a copy of the
License at
https://developer.cisco.com/docs/licenses
All use of the material herein must be in accordance with the terms of
the License. All rights not expressly granted by the License are
reserved. Unless required by applicable law or agreed to separately in
writing, software distributed under the License is distributed on an "AS
IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied.
"""
import requests
import json
import os
from dotenv import load_dotenv
from cisco.secure_access import API
from cisco.secure_access import policies, reports
from cisco.secure_access import GET
from cisco.secure_access import POST
from cisco.secure_access import PUT
from cisco.secure_access import DELETE
from cisco.secure_access import token_url
from cisco.secure_access import client_id
from cisco.secure_access import client_secret
# Application Lists API endpoints
application_lists_endpoint = "applicationLists"
application_lists_details_endpoint = "applicationLists/{}"
applications_usage_endpoint = "applications/usage"
# Reporting API > Applications API endpoints
reporting_applications_endpoint = "applications"
load_dotenv()
def get_reporting_application_ids(api):
''' Get the list of application IDs with Reporting API. '''
try:
# Get list of application IDs with Reporting API.
response = api.Query(reports, reporting_applications_endpoint, GET)
# Check if the API request was successful
if response.status_code == 200:
print(f"Success. GET Reporting API {reporting_applications_endpoint}.")
return response.json()
else:
print(f"Failed to get the list of application IDs. Status code: {response.status_code}, Response: {response.text}.")
return None
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}.")
def get_application_lists(api):
''' Get Application Lists. '''
try:
# Get the Application Lists in the organization
response = api.Query(policies, application_lists_endpoint, GET)
# Check if the API request was successful
if response.status_code == 200:
print(f"Success. GET {application_lists_endpoint}.")
return response.json()
else:
print(f"Failed to get the Application Lists. Status code: {response.status_code}, Response: {response.text}.")
return None
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}.")
def post_application_lists(api, application_ids=None, application_list_name=None, is_default=False):
''' Create an Application List. '''
try:
if application_ids is None and application_list_name is None and is_default is None:
raise ValueError("applicationIds and applicationListName are required to create the Application List.")
# Prepare the payload
payload = {
"applicationIds": application_ids,
"applicationListName": application_list_name,
"isDefault": is_default
}
# Create the Application List
response = api.Query(policies, application_lists_endpoint, POST, payload)
# Check the response status
if response.status_code == 200:
print(f"Success. POST {application_lists_endpoint}, {response.json()}")
return response.json()
else:
print(f"Failed to create the Application List. Status code: {response.status_code}, Response: {response.text}.")
return None
except Exception as e:
print(f"An error occurred: {e}.")
def get_application_list(api, application_list_id):
''' Get the properties of the Application List. '''
try:
if application_list_id is None:
raise ValueError("application_list_id is required to get the Application List.")
url = application_lists_details_endpoint.format(application_list_id)
# Get the properties for the Private Resource Group
response = api.Query(policies, url, GET)
# Check if the API request was successful
if response.status_code == 200:
print(f"Success. GET {url}, {response.json()}.")
return response.json()
else:
print(f"Failed to get the Application List {application_list_id}. Status code: {response.status_code}, Response: {response.text}.")
return
except Exception as e:
print(f"An error occurred: {e}.")
def put_application_list(api, application_list_id, application_ids=None, application_list_name=None, is_default=False):
''' Update the properties of the Application List. '''
try:
if application_list_id is None:
raise ValueError("application_list_id is required to get the Application List.")
if application_ids is None and application_list_name is None and is_default is None:
raise ValueError("application_ids and application_list_name are required to update the Application List.")
# Prepare the payload
payload = {
"applicationIds": application_ids,
"applicationListName": application_list_name,
"isDefault": is_default
}
url = application_lists_details_endpoint.format(application_list_id)
# Update the properties for the Private Resource Group
response = api.Query(policies, url, PUT, payload)
# Check if the API request was successful
if response.status_code == 200:
print(f"Success. PUT {url}, {response.json()}.")
return response.json()
else:
print(f"Failed to update the Application List {application_list_id}. Status code: {response.status_code}, Response: {response.text}.")
return
except Exception as e:
print(f"An error occurred: {e}.")
def delete_application_list(api, application_list_id):
''' Delete the Application List. '''
try:
if application_list_id is None:
raise ValueError("application_id is required to delete the Application List.")
url = application_lists_details_endpoint.format(application_list_id)
# Delete the Private Resource Group
response = api.Query(policies, url, DELETE)
# Check if the API request was successful
if response.status_code == 200:
print(f"DELETE {url} Response: {response.text}.")
return response.json()
else:
print(f"Failed to delete the Application List {application_list_id}. Status code: {response.status_code}, Response: {response.text}.")
return
except Exception as e:
print(f"An error occurred: {e}.")
def get_applications_usage(api, application_ids=None, attribute_name=None):
''' Get usage information for applications. '''
try:
if application_ids is None and attribute_name is None:
raise ValueError("application_ids and attribute_name should be used to filter the applications usage API endpoint.")
application_ids = ",".join([str(i) for i in application_ids])
url = applications_usage_endpoint + "?attributeName=" + attribute_name + "&attributeValue=" + application_ids
# Get the usage information for the applications
response = api.Query(policies, url, GET)
# Check if the API request was successful
if response.status_code == 200:
print(f"Success. GET {url}, {response.json()}")
return response.json()
else:
print(f"Failed to get the usage information for the applications. Status code: {response.status_code}, Response: {response.text}.")
return None
except requests.exceptions.RequestException as e:
print(f"An error occurred: {e}.")
def main():
# Exit out if the required client_id or client_secret is not set
for var in ['API_KEY', 'API_SECRET', 'OUTPUT_DIR']:
if os.environ.get(var) == None:
print("Required environment variable: {} not set".format(var))
exit()
# Get an API token
api = API(token_url, client_id, client_secret)
try:
# get the application lists in the organization
json_data = get_application_lists(api)
# Get list of internet application IDs from Reporting API
json_data = get_reporting_application_ids(api)
reporting_applications = json_data['data']['applications'] if 'applications' in json_data['data'] else None
reporting_categories = json_data['data']['categories'] if 'categories' in json_data['data'] else None
# get a couple of application IDs for testing
id_one = reporting_applications[0]['id']
id_two = reporting_applications[1]['id']
# create an application list
application_category_ids = []
application_ids = [id_one, id_two]
application_list_name = "new application list name"
is_default = False
json_data = post_application_lists(api, application_ids, application_list_name, is_default)
application_list_id = json_data['applicationListId'] if 'applicationListId' in json_data else None
# get an application list
json_data = get_application_list(api, application_list_id)
# update an application list
id_three = reporting_applications[2]['id']
id_four = reporting_applications[3]['id']
application_ids = [id_three, id_four]
application_list_name = "updated new application list name"
json_data = put_application_list(api, application_list_id, application_ids, application_list_name, is_default)
# get the usage information for the applications
attribute_name="umbrella.destination.application_ids"
json_data = get_applications_usage(api, application_ids, attribute_name)
if 'results' in json_data:
print(json.dumps(json_data['results']), indent=4)
# delete an application list
json_data = delete_application_list(api, application_list_id)
print(json.dumps(json_data, indent=4))
except Exception as e:
print(e)
# main
if __name__ == "__main__":
main()