Umbrella Legacy Network Device API: register a network device

Getting Started

The Umbrella Network Devices API requires an API key and token for every API request.

Base URI

The Umbrella Network Device Registration API begins with the following base URI:

https://api.opendns.com/v3/networkdevices

Response Codes

Authorization

The Umbrella Network Device Registration API requires the following Authorization header format:

Authorization: OpenDNS,api_key="<api_key>",token="<customer_token>"`

For information about creating Umbrella Network Device Registration API credentials, see Network Device Registration API Authentication.

Register a Network Device

Add a network device to Umbrella.

The response contains a unique identifier (deviceId) used by the device in EDNS queries. The Umbrella global network DNS resolvers apply policies based on the device ID.

POST /networkdevices

Request Body Fields

Field Type Description Maximum Number of Characters
model string The model name of the device. Must be unique to your organization.
Required		 50
macAddress string The MAC address of the device (formatted as 12 characters, no hyphens or colons). Must be unique.
Required		 12
label string A label for the device. Must be unique to your organization. The label identifies the device in the Umbrella dashboard.
Required		 50
serialNumber string The serial number of the device.
Required		 50
tag string A tag that describes the device or the origin assigned to the device. Must be unique to your organization. If the tag matches the name of an existing DNS policy, the device will automatically be placed in that policy. 50

Request

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

Response

Sample response (200, OK):

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

Response Fields

Field Type Description
deviceId string The unique identifier for this device. This ID is used in EDNS0 packets.
deviceKey string A descriptive unique identifier for the device. Not used by the device itself.
label string The device's label. Matches the data in the request.
serialNumber string The device's serial number. Typically matches the data in the request.
createdAt integer The time when the device registered with Umbrella. The time is defined in seconds from the Unix epoch.
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 The organization ID associated with the device. This is the same number visible in the URL for dashboard when you login.
apiKey string The API key used in the request.

Identify DNS Traffic

After registering a network device with Umbrella, add your device ID or an internal IP address to the DNS packet to create an EDNS0 packet. The EDNS0 packet format is specified by RFC6891. Umbrella defines a custom EDNS0 data option code.

Note: The only information that is required on the device is the device ID. You can register the device through a separate configuration utility using the device’s details (model, MAC address, label, and serial number). The generated device ID can be passed to the device for future use. If the device is doing the registration, each device also needs the API key and API token. The API key can be set for all devices, but the API token needs to be obtained from the specific customer dashboard and transferred to each device.

OPT RR Description

Umbrella EDNS0 data option code.

Field Type Description
Name Domain Name Empty (root domain, 0)
Type u_int16 OPT (41)
Class u_int16 Sender’s UDP payload size (default 512; Umbrella supports up to 4096)
TTL u_int32 Extended RCODE and flags (default 0)
RDLEN u_int16 Combined size in bytes of RDATA options
RDATA octet stream One or two RDATA options, formatted in {attribute,value} pairs

RDATA Description

Field Type Description
OPTION-CODE u_int16 0x6942 (hex) or 26946 (decimal)
OPTION-LENGTH u_int16 Size in octets of OPTION-DATA (15 bytes)
OPTION-DATA octet stream Data (“OpenDNS” + 8 octets of device ID)

RDATA Example

With a device ID set as 0123456789abcdef, the RDATA section of the option code consists of the following array of bytes:

[ 0x69, 0x42, 0x00, 0x0F, 0x4F, 0x70, 0x65, 0x6E, 0x44, 0x4E, 0x53, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF ]
Note: To embed remote IP address information in the EDNS packet, we recommend that you use the Umbrella Network Devices and Policies API.