The information provided in the Umbrella Investigate API is the result of statistical analysis run against DNS traffic and oriented toward security research. These results are generated from the terabytes of DNS traffic to the Umbrella DNS resolvers and not from samples of infected websites or clients. As such, they are considered to be predictors or indicators of potentially malicious domains or IPs. With the exception of the Domain Status categorization, the scores generated for any given IP or domain are intended to assist with predictive analysis and to find additional information regarding network activity deemed suspicious as part of research into security incidents.
Cisco Umbrella reserves the right to add fields to the API endpoints and methods listed below. However, we will not remove any of the endpoints listed below in future versions of the API.
Authenticate to the Investigate API by providing one of your API access tokens in the request. You can create and manage your API access tokens from your account settings. You can have multiple API access tokens active for use at a given time. Your API access tokens carry many privileges, so be sure to keep them secret and do not expose them on public web resources!
Authentication to the API occurs by providing your access token in the authorization header via HTTP Basic Auth. Provide your API access token as the basic auth username for API queries; there's no need to provide your username or password from the Investigate user interface.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must supply a valid access token in all requests.
Authentication to the Investigate GUI is controlled by the account settings. This is where you can add additional administrative accounts and provision or delete API tokens. Create and manage your API access tokens from the Investigate interface by clicking on the Setting gear in the upper right corner of the page, and selecting "API Access"
This page will be empty when you first visit it.
- To create your first API Access token, simply click create new token.
- Give the token a name and click Create. The generated token includes the email address of the person who created it and the creation date. The token is revokable by clicking the delete icon.