Getting Started
The Umbrella Dynamic Network Update API enables you to change your network host's dynamic public IP address. For more information about the Dynamic Network Update API, see Dynamic DNS API Specifications.
Note: We do not recommend using DNS-O-Matic to update your network IP address.
Overview
The Umbrella Dynamic Network Update API follows RESTful principles and uses JSON for requests and responses.
Base URI
The Umbrella Dynamic Network Update API begins with the following base URI:
https://updates.opendns.com
Authentication
The Umbrella Dynamic Network Update API requires Basic authentication. Provide your Umbrella username and password in the Authorization header for every API request.
Note: API keys, secrets, passwords, and encoded strings allow access to your private customer data. You should never share your credentials with another user or organization.
Authorization
The Umbrella Dynamic Network Update API requires an Authorization header and uses Basic authentication. To create an API request, substitute your encoded credentials in the Authorization header.
Encode Umbrella Credentials
You can run one of the sample scripts to encode your credentials.
echo -n '<username>:<password>' | openssl base64
[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('<username>:<password>'))
echo '<key>:<secret>' | python -m base64
Response Codes
The Umbrella Dynamic Network Update API does not use conventional HTTP response codes to indicate success or failure.
| Dynamic DNS Result Code | Umbrella Interpretation | Use According to Specification |
|---|---|---|
| badauth | Username and password credentials are invalid or do not match an existing Umbrella account. | The username and password pair do not match a real user. |
| nohost | Umbrella account specified does not have a network enabled for dynamic IP updates. | The hostname specified does not exist in this user account (or is not in the service specified in the system parameter). |
| good | The update was successful or not needed (the IP address has not changed since last update). Umbrella filtering and security settings are applied as configured on this network. | The update was successful, and the hostname is now updated. |
| !yours | The IP address provided is part of a larger block of addresses managed by another Umbrella administrator or the IP address is being used by someone else. | The hostname exists, but not under the username specified. |
| abuse | Umbrella received more than one update per minute for a set period of time. | The hostname specified is blocked for update abuse. |
| 911 | There is a problem or scheduled maintenance on the server side. Please contact Umbrella support. | There is a problem or scheduled maintenance on the server side. |
Update IP Address
Update an IP address.
PUT /nic/update
Note: To update a network's IP address in Umbrella with the Umbrella Dynamic Network Update API, you must make the API request while on this network.
Verify the IP Range
Before you can update a network with Umbrella, contact Cisco Umbrella Support to get your IP range verified.
Request Query Parameter
Provide your Umbrella network name with the hostname query parameter.
Request
curl -i -X PUT 'https://updates.opendns.com/nic/update?hostname=<Umbrella network name>' \
-H 'Authorization: Basic %YourEncodedUsernamePassword%' \
-H 'Content-Type: application/json'
Request example without encoded username and password.
curl -i -u '<username>:<password>' -X PUT 'https://updates.opendns.com/nic/update?hostname=<Umbrella network name>' \
-H 'Content-Type: application/json'
Response
A successful response includes the Umbrella Dynamic Network Update API good result code.
Scripting
You can use a request string in a script. For example:
https://<username>:<password>@updates.opendns.com/nic/update?hostname=<Umbrella network name>
Resources
For more information about the Cisco Umbrella Dynamic Update API, see Cisco Umbrella Knowledge Base.