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    

Register (Create) a device

POST /v1/organizations/{organizationId}/networkdevices

The device register endpoint requires that you POST information about the network device in the body of a JSON object. The application/json header with the Content-Type header name must be specified when the POST of a JSON object is performed.

This endpoint requires the organizationID be included. In the response, a unique originID field is given. This is a reference to the device itself in Umbrella for querying for detail.

The response will also contain a unique identifier (“deviceID”), 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 201/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 deviceID.

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 deviceIDs to be used by a single device (perhaps one for corporate access and one for guest access), use a different tag field.

Request Parameters

The organization's organizationID must be specified in the query string.

The body of information that must be provided is as follows below.

Type
Description

model

string

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

macAddress

string

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

name

string

A label or name for the device, this appears in the dashboard.

serialNumber

string

The serial number of the device.

tag

string

A text tag that describes the device or this particular origin assigned to the device. If the tag matches the name of an existing DNS policy, the device will automatically be placed in that policy. Optional.

Sample query:

curl -X POST -H "Content-Type: application/json" -d '{"model":"ModelName","macAddress":"0123456789ab","name":"Name1","serialNumber":"12345a","tag":"your tag"}' "https://management.api.umbrella.com/v1/organizations/<organizationId>/networkdevices" --header 'Authorization: Basic %base64string%' 

Automatic policy assignment based on tag name

Network devices can automatically be placed into a DNS policy if the tag used during registration exactly matches the name of an existing DNS policy in the organization. This behavior is carried over from the legacy network devices API, and is deprecated but still works. We recommend customers utilize the policy assignment API instead.

Responses

Success

Example return for network device create success - HTTP 201

POST https://management.api.umbrella.com/v1/organizations /{organizationId}/networkdevices
REQUEST
curl --include -H "Content-Type: application/json" 
-d '{"model":"ModelName","macAddress":"0123456789ab","name":"Name1","serialNumber":"12345a","tag":"your tag"}' \
     --header "Authorization: Basic %base64string%" \
https://management.api.umbrella.com/v1/organizations/{organizationId}/networkdevices
    
RESPONSE (HTTP 201, Content-Type: application/json)
{
  "originId": 35872943,
  "deviceId": "0123456789abcdef",
  "deviceKey": "ModelName-0123456789ab",
  "name": "Name1",
  "serialNumber": "12345a",
  "createdAt": {},
  "organizationId": 1234
}
    

Updated 28 days ago

Register (Create) a device


Suggested Edits are limited on API Reference Pages

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