Umbrella Network Devices and Policies API, register a network device

Network Devices and Policies

The Umbrella Network Devices and Policies API enables you to register a network device with Umbrella, add a network device to a policy, and get information about your organizations.

You can also:

List the network devices
Find, delete, and update a network device
List policies for the identities in the organization
Add and delete an identity in an Umbrella policy

In Umbrella, a network device is loosely defined as any hardware device that can route DNS traffic to the Umbrella recursive DNS servers. To get started, register the network device with Umbrella. Once the traffic from the device reaches the DNS servers, Umbrella identifies the organization for the device and applies DNS policies to the traffic.

Register a Network Device

Create a Network Device. Provide a Network Device object in the body of the request.

POST /organizations/{organizationId}/networkdevices

Request Body Fields

Name	Type	Description
model	string	The model name of the device. Must be unique to your organization. Required
macAddress	string	The MAC address of the device (formatted as 12 characters, no hyphens or colons). Must be unique. Required
name	string	The name of the device. Required
serialNumber	string	The serial number of the device. Required
tag	string	A text tag that describes the device or this particular origin assigned to the device. Must be unique to your organization.

Request

curl -i -X POST https://management.api.umbrella.com/v1/organizations/{organizationId}/networkdevices \
  -d '{
    "model":"device1b2",
    "macAddress":"0123456789ab",
    "name":"Name1",
    "serialNumber":"123434a"
    }'
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (201, OK):

{
  "originId": "234455",
  "deviceId": "445532",
  "deviceKey": "yy32343",
  "name": "Your organization name",
  "serialNumber": "123455",
  "createdAt": "2021-02-23T04:18:51.000Z",
  "organizationId": 1234567
}

Get Network Devices

List the network devices in your organization.

GET /organizations/{organizationId}/networkdevices

Request

curl -i GET "https://management.api.umbrella.com/v1/organizations/{organizationId}/networkdevices" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
  {
    "originId": 35872943,
    "deviceId": "0123456789abcdef",
    "deviceKey": "0123456789ab",
    "name": "APIDemoDevice",
    "serialNumber": "12345a",
    "createdAt": 2017-09-22T04:18:51.000Z,
    "organizationId": 1234
  }
]

Get Network Device Policies

List the Umbrella policies associated with a network device.

GET /organizations/{organizationId}/networkdevices/{originId}/policies

Request

curl -i GET "https://management.api.umbrella.com/v1/organizations/{organizationId}/networkdevices/{originId}/policies" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
  {
    "originId": "358729c",
    "organizationId": 1234,
    "policyId": "12312323a"
  }
]

Add Identity to Umbrella Policy

Add an identity to an Umbrella policy using the identity's originId.

PUT /organizations/{organizationId}/policies/{policyId}/identities/{originId}

Note: Policy changes may require up to 20 minutes to take affect globally.

Request Path Parameters

Name	Type	Description
organizationId	integer	The organization ID. Required
policyId	integer	The DNS or Web policy ID. Required
originId	integer	The origin ID of the identity. Required

Request

curl -i -X PUT https://management.api.umbrella.com/v1/organizations/{organizationId}/policies/{policyId}/identities/{originId} \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
  358729
}

Get Organization ID and Name

Get the list of organization ID and name for the Umbrella API key. To list the child organizations of a parent organization, provide an Umbrella API key for a Managed Service Provider (MSP), a Managed Security Service Provider (MSSP), or an Internet Service Provider (ISP).

GET /organizations

Request

curl -i GET https://management.api.umbrella.com/v1/organizations \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

[
  {
    "organizationId": 1234567,
    "name": "Your Organization Name"
  }
]

Response for Providers and Managed Providers

Sample response (200, OK):

[
  {
    "organizationId": 1234567,
    "name": "First Child Organization Name"
  },
  {
    "organizationId": 1234577,
    "name": "Second Child Organization Name"
  },
  {
    "organizationId": 1234345,
    "name": "Third Child Organization Name"
  }
]