Cisco Umbrella API

Cisco Umbrella API provides programmatic access to manage and enforce security policies across your organization's network.

Cisco Umbrella is a cloud-delivered security platform that provides the first line of defense against threats on the internet. It offers robust capabilities for managing and automating destination lists, domains, URLs, and IP addresses. By integrating Cisco Umbrella API with Swimlane Turbine, users can automate the management of destination lists, streamline threat response, and enhance security operations with minimal manual intervention. This integration empowers security teams to efficiently manage web access policies and respond to threats in real-time, leveraging the comprehensive capabilities of Cisco Umbrella within the Swimlane platform.

Prerequisites

Before you can use the Cisco Umbrella API connector for Turbine, you'll need access to the Cisco Umbrella API. This requires the following:

Custom authentication using OAuth 2.0 client credentials with the following parameters:

URL: The base URL for the Cisco Umbrella API.

API Key: A unique key provided by Cisco Umbrella for API access.

Key Secret: A secret key associated with the API Key for secure authentication.

Authentication Methods

You need both an API Key and a Key Secret.

URL: Base URL for the Umbrella API (default: https://api.umbrella.com/).

API Key: API Key ID.

Key Secret: API Key Secret.

Verify SSL Certificates: (Optional)

HTTP(s) Proxy: (Optional)

See Umbrella API Authentication.

Capabilities

This Cisco Umbrella API connector provides the following capabilities:

Create Destination List

Get Destination Lists

Delete Destination List

Add Destinations to Destination List

Add Destinations to Destination List Base64 CSV

Create Destination

Get Destinations

Delete Destination

Delete Destinations from Destination List

Create Destination List

Create a destination list in your organization. Set bundleTypeId to 2, isGlobal to false, and prefer access of none when creating lists for use in policy rules. Destinations may be type DOMAIN, URL, or IPV4.

Cisco's documentation for this action can be found here.

Get Destination Lists

Get the destination lists in your organization.

Cisco's documentation for this action can be found here.

Delete Destination List

Remove a destination list from your organization using the specified destinationListId.

Cisco's documentation for this action can be found here.

Add Destinations to Destination List

Add destinations (domain, URL, or IPv4) to a destination list. A domain is one type of destination.

Cisco's documentation for this action can be found here.

Add Destinations to Destination List Base64 CSV

Add destinations to a destination list using a base64-encoded CSV string. Uses the same Umbrella API as Add Destinations to Destination List.

Cisco's documentation for this action can be found here.

Create Destination

Add destinations to an existing destination list. A domain is one type of destination (also URL or IPv4).

Cisco's documentation for this action can be found here.

Get Destinations

Get destinations in a destination list. Destinations may be domains, URLs, or IPv4 addresses.

Cisco's documentation for this action can be found here.

Delete Destination

Remove specified destinations from a destination list using the provided destinationListId.

Cisco's documentation for this action can be found here.

Delete Destinations from Destination List

Remove destinations from a destination list by destination ID (max 500 IDs per request). Use Get Destinations to obtain IDs.

Cisco's documentation for this action can be found here.

Notes

Umbrella Destination Lists API overview

The Secure Access twin connector uses api.sse.cisco.com instead of api.umbrella.com

Configurations

Cisco Umbrella OAuth 2.0 Client Authentication

Authenticates with API Key ID and Key Secret via OAuth 2.0 client credentials. Umbrella API base is https://api.umbrella.com/ (Secure Access uses https://api.sse.cisco.com/).

Configuration Parameters

Parameter	Description	Type	Required
url	Base URL for the Cisco Umbrella API (default https://api.umbrella.com/). Destination list paths are under policies/v2.	string	Required
api_key	API Key ID.	string	Required
api_secret	API Key Secret.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Add Destinations to Destination List

Add domains, URLs, or IPs to a destination list in Cisco Umbrella using the destinationListId path parameter.

Endpoint

URL: policies/v2/destinationlists/{{destinationListId}}/destinations

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.destinationListId	string	Required	The unique ID of the destination list.

Input Example

{"json_body":[{"destination":"mydestination.com","comment":"A comment about the destination"}],"path_parameters":{"destinationListId":"17489153"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	object	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	number	Response data
data.modifiedAt	number	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"317","Connection":"keep-alive","RateLimit-Reset":"60","RateLimit-Remaining":"1999","RateLimit-Limit":"2000","X-RateLimit-Limit-minute":"2000","X-RateLimit-Remaining-minute":"1999","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5998","Date":"Mon, 20 Apr 2026 06:51:00 GMT","X-Powered-By":"Express","Vary":"Origin","Access-Control-Allow-Credentials":"true","ETag":"W/\"13d-ri072AfI...

Add Destinations to Destination List Base64 CSV

Add destinations to a Cisco Umbrella destination list using a base64-encoded CSV string. Requires 'base64_string' and 'umbrella_destinationlist_id'.

Endpoint

Method: POST

Input

Argument Name	Type	Required	Description
base64_string	string	Required	Base64 String encoded CSV file of the destination data.
umbrella_destinationlist_id	string	Required	The ID of the destination list.

Input Example

{"base64_string":"aWQsZGVzdGluYXRpb24sdHlwZSxjb21tZW50LGNyZWF0ZWRBdAoxNTYsd3d3LnN3aW1sYW5lLmNvbSxkb21haW4sbm9uZSwyMDIxLTAzLTI0IDExOjU5OjQ1Cg==","umbrella_destinationlist_id":"17489153"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	object	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	number	Response data
data.modifiedAt	number	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"317","Connection":"keep-alive","X-RateLimit-Limit-minute":"2000","RateLimit-Reset":"11","X-RateLimit-Remaining-hour":"5995","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-minute":"1998","RateLimit-Remaining":"1998","RateLimit-Limit":"2000","Date":"Mon, 23 Sep 2024 06:46:49 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POS...

Delete Destinations from Destination List

Remove destinations from a Cisco Umbrella destination list using the destinationListId. A domain is one type of destination.

Endpoint

URL: policies/v2/destinationlists/{{destinationListId}}/destinations/remove

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.destinationListId	string	Required	The unique ID of the destination list.

Input Example

{"json_body":[154],"path_parameters":{"destinationListId":"9891773"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	object	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	number	Response data
data.modifiedAt	number	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"311","Connection":"keep-alive","X-RateLimit-Remaining-minute":"1998","X-RateLimit-Remaining-hour":"5998","X-RateLimit-Limit-minute":"2000","RateLimit-Remaining":"1998","RateLimit-Limit":"2000","RateLimit-Reset":"16","X-RateLimit-Limit-hour":"6000","Date":"Tue, 10 Dec 2024 08:39:45 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POS...

Create Destination List

Create a destination list in Cisco Umbrella with specified bundle type, access level, name, and global setting. Supports domain, URL, or IPv4 destinations.

Endpoint

URL: policies/v2/destinationlists

Method: POST

Input

Argument Name	Type	Required	Description
bundleTypeId	number	Optional	The type of the destination list. Set to 2 when creating a destination list (web profiles applied on access rules).
access	string	Optional	Access type for the destination list. Prefer none when creating lists for use in policy rules.
isGlobal	boolean	Optional	Whether the destination list is global. Set to false when creating a destination list.
name	string	Optional	The name of the destination list.
destinations	array	Optional	Optional destinations to include. A domain is one type of destination (also URL or IPv4).
destinations.comment	string	Optional	The comment about the destination.
destinations.destination	string	Optional	A domain, URL, or IP.
destinations.type	string	Optional	The type of the destination.

Input Example

{"json_body":{"bundleTypeId":2,"access":"none","isGlobal":false,"name":"New Destination List","destinations":[{"comment":"Comment","destination":"google.com","type":"DOMAIN"}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	object	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	number	Response data
data.modifiedAt	number	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"329","Connection":"keep-alive","X-RateLimit-Limit-minute":"2000","RateLimit-Remaining":"1998","RateLimit-Limit":"2000","RateLimit-Reset":"27","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5997","X-RateLimit-Remaining-minute":"1998","Date":"Mon, 23 Sep 2024 05:17:34 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POS...

Create Destination

Add domains, URLs, or IPv4 addresses to a destination list in Cisco Umbrella using the specified destinationListId.

Endpoint

URL: policies/v2/destinationlists/{{destinationListId}}/destinations

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.destinationListId	number	Required	The unique ID of the destination list.

Input Example

{"json_body":[{"destination":"mydestination.com","comment":"A comment about the destination"}],"path_parameters":{"destinationListId":9891773}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	object	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	number	Response data
data.modifiedAt	number	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"311","Connection":"keep-alive","X-RateLimit-Limit-minute":"2000","RateLimit-Reset":"2","RateLimit-Remaining":"1999","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5999","RateLimit-Limit":"2000","X-RateLimit-Remaining-minute":"1999","Date":"Mon, 23 Sep 2024 04:29:58 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POST...

Delete Destination List

Remove a specified destination list from Cisco Umbrella using the unique destinationListId provided.

Endpoint

URL: policies/v2/destinationlists/{{destinationListId}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.destinationListId	string	Required	Parameters for the Delete Destination List action

Input Example

{"path_parameters":{"destinationListId":"18075958"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
data	array	Response data
data.file_name	string	Response data
data.file	string	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"45","Connection":"keep-alive","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5994","RateLimit-Reset":"56","X-RateLimit-Limit-minute":"2000","X-RateLimit-Remaining-minute":"1999","RateLimit-Remaining":"1999","RateLimit-Limit":"2000","Date":"Mon, 23 Sep 2024 05:58:04 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POST...

Get All Destination Lists

Retrieve all destination lists associated with your organization in Cisco Umbrella Management.

Endpoint

URL: policies/v2/destinationlists

Method: GET

Input

Argument Name	Type	Required	Description
parameters.page	number	Optional	The number of a page in the collection.
parameters.limit	number	Optional	The number of records in the collection to return on the page.

Input Example

{"parameters":{"page":1,"limit":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
meta	object	Output field: meta
meta.page	number	Output field: meta.page
meta.limit	number	Output field: meta.limit
meta.total	number	Output field: meta.total
data	array	Response data
data.id	number	Response data
data.organizationId	number	Response data
data.access	string	Response data
data.isGlobal	boolean	Response data
data.name	string	Response data
data.thirdpartyCategoryId	object	Response data
data.createdAt	string	Response data
data.modifiedAt	string	Response data
data.isMspDefault	boolean	Response data
data.markedForDeletion	boolean	Response data
data.bundleTypeId	number	Response data
data.meta	object	Response data
data.meta.destinationCount	number	Response data
data.meta.domainCount	number	Response data
data.meta.urlCount	number	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"1178","Connection":"keep-alive","X-RateLimit-Limit-minute":"2000","X-RateLimit-Remaining-minute":"1999","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5997","RateLimit-Limit":"2000","RateLimit-Remaining":"1999","RateLimit-Reset":"40","Access-Control-Allow-Origin":"*","Surrogate-Control":"no-store","Cache-Control":"no-store, no-cache, must-revalidate, proxy-revalidate","Pragma"...

Get Destinations

Retrieve domains, URLs, or IPv4 addresses from a specified destination list in Cisco Umbrella. Requires the destinationListId as a path parameter.

Endpoint

URL: policies/v2/destinationlists/{{destinationListId}}/destinations

Method: GET

Input

Argument Name	Type	Required	Description
parameters.page	number	Optional	The number of a page in the collection.
parameters.limit	number	Optional	The number of records in the collection to return on the page.
path_parameters.destinationListId	number	Required	The unique ID of the destination list.

Input Example

{"parameters":{"page":1,"limit":100},"path_parameters":{"destinationListId":9891773}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
status	object	Status value
status.code	number	Status value
status.text	string	Status value
meta	object	Output field: meta
meta.page	number	Output field: meta.page
meta.limit	number	Output field: meta.limit
meta.total	number	Output field: meta.total
data	array	Response data
data.id	string	Response data
data.destination	string	Response data
data.type	string	Response data
data.comment	string	Response data
data.createdAt	string	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"423","Connection":"keep-alive","X-RateLimit-Limit-minute":"2000","X-RateLimit-Limit-hour":"6000","X-RateLimit-Remaining-hour":"5994","RateLimit-Reset":"57","RateLimit-Remaining":"1997","RateLimit-Limit":"2000","X-RateLimit-Remaining-minute":"1997","Date":"Sun, 22 Sep 2024 10:06:03 GMT","X-Powered-By":"Express","Access-Control-Allow-Credentials":"true","Access-Control-Allow-Methods":"GET, POS...

Response Headers

Header	Description	Example
Access-Control-Allow-Credentials	HTTP response header: Access-Control-Allow-Credentials	true
Access-Control-Allow-Headers	HTTP response header: Access-Control-Allow-Headers	content-type
Access-Control-Allow-Methods	HTTP response header: Access-Control-Allow-Methods	GET, POST, OPTIONS, PUT, PATCH, DELETE
Access-Control-Allow-Origin	HTTP response header: Access-Control-Allow-Origin	*
Access-Control-Max-Age	HTTP response header: Access-Control-Max-Age	1800
Cache-Control	Directives for caching mechanisms	no-store, no-cache, must-revalidate, proxy-revalidate
Connection	HTTP response header: Connection	keep-alive
Content-Length	The length of the response body in bytes	317
Content-Security-Policy	HTTP response header: Content-Security-Policy	default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self'; img-src 'self'; report-uri ''; object-src 'none'
Content-Type	The media type of the resource	application/json; charset=utf-8
Date	The date and time at which the message was originated	Mon, 23 Sep 2024 06:46:49 GMT
ETag	An identifier for a specific version of a resource	W/"1a7-bAM/7yGip/L52rLQ0jiO1fIn1w4"
Expires	The date/time after which the response is considered stale	0
Pragma	HTTP response header: Pragma	no-cache
RateLimit-Limit	HTTP response header: RateLimit-Limit	2000
RateLimit-Remaining	HTTP response header: RateLimit-Remaining	1997
RateLimit-Reset	HTTP response header: RateLimit-Reset	40
Referrer-Policy	HTTP response header: Referrer-Policy	no-referrer
Set-Cookie	HTTP response header: Set-Cookie	connect.sid=s%3AjhmWf5CvPb2RVl5y5VGQUksIunmU__uM.1i3lNN7v202yhIv5vucb0KfGWxJseSd%2BPfyRnwFzEzE; Path=/; HttpOnly
Strict-Transport-Security	HTTP response header: Strict-Transport-Security	max-age=31536000; includeSubDomains
Surrogate-Control	HTTP response header: Surrogate-Control	no-store
Vary	HTTP response header: Vary	Origin
X-Content-Security-Policy	HTTP response header: X-Content-Security-Policy	default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self'; img-src 'self'; report-uri ''; object-src 'none'
X-Content-Type-Options	HTTP response header: X-Content-Type-Options	nosniff
X-DNS-Prefetch-Control	HTTP response header: X-DNS-Prefetch-Control	off
X-Download-Options	HTTP response header: X-Download-Options	noopen
X-Frame-Options	HTTP response header: X-Frame-Options	DENY
X-Powered-By	HTTP response header: X-Powered-By	Express
X-RateLimit-Limit-hour	HTTP response header: X-RateLimit-Limit-hour	6000
X-RateLimit-Limit-minute	HTTP response header: X-RateLimit-Limit-minute	2000
X-RateLimit-Remaining-hour	HTTP response header: X-RateLimit-Remaining-hour	5997
X-RateLimit-Remaining-minute	HTTP response header: X-RateLimit-Remaining-minute	1997
X-WebKit-CSP	HTTP response header: X-WebKit-CSP	default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self'; img-src 'self'; report-uri ''; object-src 'none'
X-XSS-Protection	HTTP response header: X-XSS-Protection	1; mode=block

Docs powered by Archbee