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

The Umbrella Reporting API is available in two versions; legacy (v1) and the current version, v2. The Reporting API v1 is a more limited system enabling access to three endpoints. While v1 is simple and secure, the Reporting API v2 is more scalable. You can access more than 30 endpoints with v2, which also reduces query cycles. In addition, V2 offers an approach to searching and filtering that goes beyond simple one-to-one matching.

Authentication differences

For v1, the key and secret values used to authenticate requests for this API can be created by logging in to the Umbrella dashboard for the organization and clicking Admin -> API Keys -> "+" (the Add button icon at the top right hand corner of the screen) -> select "Umbrella Reporting" -> Create.

For v2, you need the key and secret created by logging in to the Umbrella dashboard for the organization and clicking Admin -> API Keys -> "+" (the Add button icon at the top right hand corner of the screen) -> select "Umbrella Reporting" -> Create. You then use those credentials to generate a short-lived token to use against the reporting API by issuing an HTTP Basic Auth request to https://management.api.umbrella.com/auth/v2/oauth2/token with the key and secret supplied as the username and password.

Enabling API access in US and EU locations

Umbrella maintains data warehouses in the US and in the EU. If you store data in the US but are submitting an API call from outside the US, you will get a 302 error when attempting to redirect to the US API URL (api.us.reports.umbrella.com). If you are geographically in the US but store the data in the EU data warehouse, you will get a 302 error when attempting to redirect to the EU API servers (api.eu.reports.umbrella.com).

In order to enable access if you are using cURL, use -L to follow the redirect, and use --location-trusted to pass the authentication token to the redirected URL.

If you are using an app such as Postman, redirects may be turned on by default but not include the auth header in the redirect. This results in a 401 error. Turning on "follow authorization header" allows the request to work.

V1 Endpoints

The Reporting API v1 includes the following endpoints:

V2 Endpoints

For a list of V2 endpoints, refer to Reporting API V2 Endpoints.

Updated 16 days ago

Overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.