The OpenDNS Network Devices API Developer Hub

Welcome to the OpenDNS Network Devices API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Network Devices API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Overview

This API is for MSP, MSSP, and Multi-Org Console administrators. It displays summary information that is available only in those Consoles. Authentication is handled entirely through the Console, although the data gathered reflects the customer or "child" organizations managed by that Console.

The Console Reporting API has two endpoints:

/security-summary – Security summary: provides the total requests and the total requests blocked for all the child organizations in aggregate, as well the same information about each child organization.

/detailed-summary – Deployment summary: provides the total deployment status for all customers of the Console, as well as deployment details about each child organization of the Console.

Requests for these reports are made to https://reports.api.umbrella.com/v1/organizations/{ConsoleID}/{endpoint}.
All API methods are standard HTTP GET requests and JSON is returned in all responses.

All data for the two summary endpoints (security and deployment) is for the previous 24 hours only; this time period cannot be extended, although the results can be refined.

Authentication and Key Management

Authentication to the API is handled via HTTP basic authentication. We use a special HTTP header where we add 'key:secret' encoded in base64. All API requests are sent over HTTPS so no data is insecure.

  1. Navigate from the Console main page to (MSP or MSSP or Console) Settings > API Keys.
    Note: If you cannot access this page, you'll need to have the API Keys feature enabled for your account. Contact umbrella-support@cisco.com or your Umbrella representative.
  1. Click Add.

This will open a small modal window that asks you to supply a name for your API Key. Give it a name that is easy to remember— the name is cosmetic—and click ‘Create Key’.

IMPORTANT:

You have only one opportunity to copy the secret that is displayed next. Secrets are not stored within Umbrella and can not be resurfaced after the initial creation.

Authenticating API Requests

All queries require that you use the key and secret in combination when making a request. Using the -u with curl in the example query below will base64 encode the key:secret pair and add it to the Authorization header as "Basic %base64string%" This is helpful for testing, but you can also base64 encrypt the credentials yourself and pass the header in all queries that way.

An unsuccessful authentication query will result in a 403 Forbidden "Invalid authentication credentials" error. A query that doesn't specify the {ConsoleID}/{endpoint} will result in a 404 "Not Found" error.

Do not share your API credentials!

Keys, secrets and encoded strings allow access to your private customer data in Umbrella. They should never be shared outside of your company.

Example queries:

Allowing curl to generate the basic authentication header:

curl -u 'key:secret'  --url 
"https://reports.api.umbrella.com/v1/organizations"

or

curl -i -X GET --url 'https://reports.api.umbrella.com/v1/organizations' \
 	--user 'key:secret'

We recommend simply generating your own header. You can use a base64 encoding tool such as https://www.base64encode.org/

As an example, if the credential uses ABCD as the key and 1234 as the secret, then the field's value is the base64 encoding of ABCD:1234, or QUJDRDoxMjM0

Then the Authorization header must appear as:
Authorization: Basic QUJDRDoxMjM0 and placed in the query as follows:

curl -i -X GET --url 'https://reports.api.umbrella.com/v1/organizations' \
 	--header 'Authorization: Basic %base64string%'

NOTE

If you're unfamiliar with using curl to perform commands, several excellent UI-based tools exist to use in testing basic queries. The free Postman app (https://www.getpostman.com/) is a good example.

Limitations

Umbrella Console API enforces a strict rate limit of 5 requests per minute for all endpoints.