Cisco Umbrella Providers

Cisco Umbrella Providers connector facilitates management of customer data and operations within the Cisco Umbrella platform.

Cisco Umbrella is a cloud-delivered security service that provides protection against internet threats. The Cisco Umbrella Providers connector enables seamless integration with Swimlane Turbine, allowing users to automate customer management tasks such as creating, updating, and deleting customer records. This integration enhances operational efficiency by streamlining customer management processes, reducing manual effort, and ensuring accurate data handling within the Cisco Umbrella ecosystem.

Prerequisites

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

Custom authentication using Umbrella API Key ID and Key Secret (OAuth 2.0 client credentials):

URL: The endpoint URL for accessing Cisco Umbrella services.

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

Cisco Umbrella OAuth 2.0 Client Authentication

You need both an API Key and a Key Secret. HTTP Basic against management.api.umbrella.com is no longer supported.

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

API Key: Umbrella API Key ID.

Key Secret: Umbrella API Key Secret.

Verify SSL Certificates: (Optional) Enable or disable SSL certificate verification.

HTTP(s) Proxy: (Optional) A proxy URL to route requests through.

Token endpoint used by the connector: https://api.umbrella.com/auth/v2/token.

See Umbrella API Authentication.

Capabilities

Create Customer for Provider

Get Customer for Provider

Update Customer for Provider

Delete Customer for Provider

List Customers for Provider

Create Customer for Managed Provider

Get Customer for Managed Provider

Update Customer for Managed Provider

Delete Customer for Managed Provider

List Customers for Managed Provider

Create Customer for Provider

Create a customer for a provider (SP/MSSP).

Cisco documentation: Create Customer for Provider.

Get Customer for Provider

Get a customer for the provider (SP/MSSP).

Cisco documentation: Get Customer for Provider.

Update Customer for Provider

Update a customer for a provider (SP/MSSP).

Cisco documentation: Update Customer for Provider.

Delete Customer for Provider

Delete a customer for a provider (SP/MSSP).

Cisco documentation: Delete Customer for Provider.

List Customers for Provider

List customers for the provider (SP/MSSP).

Cisco documentation: List Customers for Provider.

Create Customer for Managed Provider

Create a customer for a managed provider (MSP/multiOrg).

Cisco documentation: Create Customer for Managed Provider.

Get Customer for Managed Provider

Get a customer for the managed provider (MSP/multiOrg).

Cisco documentation: Get Customer for Managed Provider.

Update Customer for Managed Provider

Update a customer for a managed provider (MSP/multiOrg).

Cisco documentation: Update Customer for Managed Provider.

Delete Customer for Managed Provider

Delete a customer for the managed provider (MSP/multiOrg).

Cisco documentation: Delete Customer for Managed Provider.

List Customers for Managed Provider

List customers for the managed provider (MSP/multiOrg).

Cisco documentation: List Customers for Managed Provider.

Configurations

Cisco Umbrella OAuth 2.0 Client Authentication

Authenticates using Umbrella API Key ID and Key Secret (OAuth 2.0 client credentials).

Configuration Parameters

Parameter	Description	Type	Required
url	Base URL for the Cisco Umbrella Admin API (providers and managed providers).	string	Required
api_key	Umbrella API Key ID.	string	Required
api_secret	Umbrella API Key Secret.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Create Customer for Managed Provider

Create a customer for a managed provider in Cisco Umbrella. Requires customerName and seats in the JSON body.

Endpoint

URL: /managed/customers

Method: POST

Input

Argument Name	Type	Required	Description
customerName	string	Optional	The name of the customer's organization.
seats	number	Optional	The number of users.

Input Example

{"json_body":{"customerName":"Cisco","seats":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
customerId	number	Unique identifier
customerName	string	Name of the resource
seats	number	Output field: seats

Output Example

{"status_code":200,"reason":"OK","json_body":{"customerId":12929,"customerName":"cisco","seats":1000}}

Create Customer for Provider

Create a customer for a provider in Cisco Umbrella using details like packageId, seats, city, countryCode, customerName, streetAddress, and adminEmails.

Endpoint

URL: /providers/customers

Method: POST

Input

Argument Name	Type	Required	Description
customerName	string	Optional	The name of the customer's organization.
seats	number	Optional	The number of users.
addonRbi	string	Optional	Remote Browser Isolation Add-On.
dealId	string	Optional	The deal ID.
licenseType	string	Optional	The customer's license type.
streetAddress	string	Optional	The street address for the customer.
streetAddress2	string	Optional	The second street address for the customer.
zipCode	string	Optional	The zip code of the customer's organization.
addonCdfwL7	boolean	Optional	L7 Cloud Delivered Firewall Solution.
addonDlp	boolean	Optional	Data Loss Prevention Add-On.
isTrial	boolean	Optional	Specify whether the customer is a trial with an MSSP with SPLA (MSLA) license.
city	string	Optional	The name of the city where the customer's organization is located.
state	string	Optional	The name of the customer's state.
countryCode	string	Optional	The country code of the customer's organization.
packageId	number	Optional	The ID of the Umbrella package.
adminEmails	array	Optional	Parameter for Create Customer for Provider
ccwDealOwnerEmails	array	Optional	Parameter for Create Customer for Provider

Input Example

{"json_body":{"customerName":"cisco","seats":1000,"addonRbi":"0","dealId":"1234567890","licenseType":"msla","streetAddress":"123 Customer Way","streetAddress2":"123a mystreet2 Place","zipCode":"12345","addonCdfwL7":true,"addonDlp":true,"isTrial":true,"city":"San Jose","state":"CA","countryCode":"1a","packageId":250,"adminEmails":["[email protected]"],"ccwDealOwnerEmails":["[email protected]"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
customerId	number	Unique identifier
customerName	string	Name of the resource
licenseType	string	Type of the resource
packageName	string	Name of the resource
seats	number	Output field: seats
streetAddress	string	Output field: streetAddress
streetAddress2	string	Output field: streetAddress2
city	string	Output field: city
state	string	Output field: state
countryCode	string	Output field: countryCode
zipCode	string	Output field: zipCode
packageId	number	Unique identifier
dealId	string	Unique identifier
adminEmails	array	Output field: adminEmails

Output Example

{"status_code":200,"reason":"OK","json_body":{"customerId":1234,"customerName":"myCustomerName","licenseType":"theLicenseType","packageName":"Umbrella SIG Essentials","seats":1000,"streetAddress":"123 myStreet Rd.","streetAddress2":"123a mystreet2 Place","city":"myCity","state":"CA","countryCode":"12a","zipCode":"12345a","packageId":101,"dealId":"myDealId","adminEmails":["[email protected]"]}}

Delete Customer for Managed Provider

Delete a customer for the managed provider in Cisco Umbrella using the required customerId path parameter.

Endpoint

URL: /managed/customers/{{customerId}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.

Input Example

{"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"reason":"OK","json_body":{}}

Delete Customer for Provider

Remove a customer from a provider in Cisco Umbrella Managed Service Providers using the customerId path parameter.

Endpoint

URL: /providers/customers/{{customerId}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.

Input Example

{"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"reason":"OK","json_body":{}}

Get Customer for Managed Provider

Retrieve customer details for a managed provider in Cisco Umbrella using the customerId path parameter.

Endpoint

URL: /managed/customers/{{customerId}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.

Input Example

{"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
message	string	Response message

Output Example

{"status_code":200,"reason":"OK","json_body":{"message":"Customer retrieved successfully"}}

Get Customer for Provider

Get details of a specific customer for the provider in Cisco Umbrella using the customerId path parameter.

Endpoint

URL: /providers/customers/{{customerId}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.

Input Example

{"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
customerId	number	Unique identifier
customerName	string	Name of the resource
licenseType	string	Type of the resource
packageName	string	Name of the resource
seats	number	Output field: seats
streetAddress	string	Output field: streetAddress
streetAddress2	string	Output field: streetAddress2
city	string	Output field: city
state	string	Output field: state
countryCode	string	Output field: countryCode
zipCode	string	Output field: zipCode
packageId	number	Unique identifier
dealId	string	Unique identifier
adminEmails	array	Output field: adminEmails

Output Example

List Customers for Managed Provider

List the customers associated with a managed provider in Cisco Umbrella.

Endpoint

URL: /managed/customers

Method: GET

Input

Argument Name	Type	Required	Description
parameters.limit	number	Optional	The number of customers to return.
parameters.page	number	Optional	The page number.

Input Example

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

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"reason":"OK","json_body":[{"customerId":12929,"customerName":"cisco","seats":1000}]}

List Customers for Provider

List all customers associated with a Cisco Umbrella Managed Service Provider.

Endpoint

URL: /providers/customers

Method: GET

Input

Argument Name	Type	Required	Description
parameters.limit	number	Optional	The number of customers to return.
parameters.page	number	Optional	The page number to return.

Input Example

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

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"reason":"OK","json_body":[{"customerId":1234,"customerName":"myCustomerName","licenseType":"theLicenseType","packageName":"Umbrella SIG Essentials","seats":1000,"streetAddress":"123 myStreet Rd.","streetAddress2":"123a mystreet2 Place","city":"myCity","state":"CA","countryCode":"12a","zipCode":"12345a","packageId":101,"dealId":"myDealId","adminEmails":[]}]}

Update Customer for Managed Provider

Update customer details for a managed provider in Cisco Umbrella. Requires customerId as a path parameter and customerName, seats in the JSON body.

Endpoint

URL: /managed/customers/{{customerId}}

Method: PUT

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.
customerName	string	Optional	The name of the customer's organization.
seats	number	Optional	The number of users.

Input Example

{"json_body":{"customerName":"cisco","seats":1000},"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
customerId	number	Unique identifier
customerName	string	Name of the resource
seats	number	Output field: seats

Output Example

{"status_code":200,"reason":"OK","json_body":{"customerId":12929,"customerName":"cisco","seats":1000}}

Update Customer for Provider

Update customer information for a provider in Cisco Umbrella, requiring customerId, packageId, seats, city, countryCode, customerName, streetAddress, and adminEmails.

Endpoint

URL: /providers/customers/{{customerId}}

Method: PUT

Input

Argument Name	Type	Required	Description
path_parameters.customerId	number	Required	The ID of the customer.
customerName	string	Optional	The name of the customer's organization.
seats	number	Optional	The number of users.
dealId	string	Optional	The deal ID.
streetAddress	string	Optional	The street address for the customer.
streetAddress2	string	Optional	The second street address for the customer.
zipCode	string	Optional	The zip code of the customer's organization.
city	string	Optional	The name of the city where the customer's organization is located.
state	string	Optional	The name of the state where the customer's organization is located.
countryCode	string	Optional	The country code of the customer's organization.
packageId	number	Optional	The ID of the Umbrella package.
adminEmails	array	Optional	The email addresses of the customer's administrators.
ccwDealOwnerEmails	array	Optional	The email addresses of the customer's CCW deal owner.

Input Example

{"json_body":{"customerName":"cisco","seats":1000,"dealId":"1234567890","streetAddress":"123 Customer Way","streetAddress2":"123a mystreet2 Place","zipCode":"12345","city":"San Jose","state":"CA","countryCode":"1a","packageId":250,"adminEmails":["[email protected]"],"ccwDealOwnerEmails":["[email protected]"]},"path_parameters":{"customerId":1234}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
customerId	number	Unique identifier
customerName	string	Name of the resource
licenseType	string	Type of the resource
packageName	string	Name of the resource
seats	number	Output field: seats
streetAddress	string	Output field: streetAddress
streetAddress2	string	Output field: streetAddress2
city	string	Output field: city
state	string	Output field: state
countryCode	string	Output field: countryCode
zipCode	string	Output field: zipCode
packageId	number	Unique identifier
dealId	string	Unique identifier
adminEmails	array	Output field: adminEmails

Output Example

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT