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    

Registration API Endpoint

POST the appropriate data (as below) to the Registration API Endpoint to register a device into the customer dashboard.

The Registration API Endpoint is:
https://api.opendns.com/v3/networkdevices

The response will contain a unique identifier (“Device ID”), which should be stored and used in EDNS queries by the device. This identifier is how the Cisco Umbrella's global network DNS resolvers will know how to apply the proper customer policy for this specific device.

If you attempt to register a device that already exists, the API will return the same 200/OK with response data as if it had registered the first time. This allows a device with the same model and MAC address to retain the same identity even if the stored device loses its Device ID.

The combination of model, MAC address, and (optional) tag must be unique within the organization. If you would like to register a particular device multiple times and receive multiple Device IDs to be used by a single device (perhaps one for corporate access and one for guest access), use a different tag field.

Example Request

curl -X POST 'https://api.opendns.com/v3/networkdevices' -H 'Authorization:OpenDNS,api_key="<API_KEY>",token="<CUSTOMER_TOKEN>"' -d '{"model":"ModelName","macAddress":"0123456789ab","label":"Label1","serialNumber":"12345a"}'

Parameters for input

Field
Type
Description
Max. Length

model

string

The model name of the device. Must be unique to your organization.

50 characters

macAddress

string

The MAC address of the device (formatted as 12 characters, no hyphens or colons). Must be unique.

12 characters

label

string

A label for the device. This is how the device will be designated in the customer’s Umbrella dashboard. This label should be unique to your organization.

50 characters

serialNumber

string

The serial number of the device.

50 characters

tag

string

[Optional] A text tag that describes the device or this particular origin assigned to the device. Must be unique to your organization.

50 characters

Example Response

{"deviceId":"0123456789abcdef","deviceKey":"ModelName-0123456789ab","label":"Label1","serialNumber":"12345a","createdAt":1445009654,"originId":35872943,"apiKey":"<API_KEY>","vendorId":51, "organizationId":1234}

Returned value for output if Success 200

Field
Type
Descriptions

deviceId

string

The unique identifier for this specific device. This is the identifier that should be inserted into EDNS packets.

deviceKey

string

A more descriptive unique identifier for the device. Not used by the device itself.

label

string

The device’s label—typically matches the data in the POST.

serialNumber

string

The device’s serial number—typically matches the data in the POST.

createdAt

integer

The Unix timestamp that the device was created.

originId

integer

An internal identifier for the device. Not used by the device itself.

vendorId

integer

An identifier for the vendor associated with this device. This is tied to the API Key used during registration.

organizationId

integer

An identifier of the organization with which this device is now associated. This is the same number visible in the URL for dashboard when you login.

apiKey

string

The API key used in the request.


Errors < Registration API Endpoint > Identifying DNS Traffic