The Management API Developer Hub

Welcome to the Management API developer hub. You'll find comprehensive guides and documentation to help you start working with the Management API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Getting Started with the Management API

Follow the instructions below to get started with the Management API.

Overview

The Umbrella Management API enables direct customers, SPs, MSPs, and MSSPs to manage organizations, networks, network devices, users, and roaming computers, and integrate actions in those areas into your workflows.

The Management API isa REST API with JSON responses. All requests must include your API key and secret. To do that in cURL, use the -u option: -u 'key:secret'

For more information about authentication in Umbrella APIs, see:
About the Umbrella Console API endpoints.

For complete information about the Management API calls, see the API Reference.

1. To begin, generate an API key

Umbrella Dashboard: Navigate to Admin > API Keys, then click Add.

Management Consoles (Multi-org, MSP, MSSP): Navigate to Settings > API Keys, then click Add.

  1. In the What should this API do? modal, select "Umbrella Network Devices", "Legacy Network Devices", "Umbrella Reporting", or "Umbrella Management" as appropriate, then click Create.

Important

You have only one opportunity to copy the secret that is displayed next. Secrets are not stored within Umbrella and can not be resurfaced after the initial creation.

  1. The key and secret appear. Acknowledge that the secret can be seen only once by clicking the checkbox, then click Close.

Legacy API Token

If you selected Legacy Network Devices, you receive an API Token rather than a secret and key.

To generate a new key and secret, click the refresh button on your existing key and secret. Alternatively, delete the existing key and secret, then create a new key/secret pair.

Authenticating API Requests

All queries require that you use the key and secret in combination when making a request. In cURL, use the -u option to base64-encode the key:secret pair and add it to the Authorization header as Basic %base64string% You can also base64-encrypt the credentials yourself and pass the header in queries that way.

Do not share your API credentials!

Keys, secrets and encoded strings allow access to your private customer data in Umbrella. They should never be shared outside of your company.

Example queries

Allowing cURL to generate the header:

curl -u 'key:secret'  --url "https://management.api.umbrella.com/v1/organizations"
curl -i -X GET --url "https://management.api.umbrella.com/v1/organizations" \
 	--user 'key:secret'

We recommend simply generating your own header. You can use a base64 encoding tool such as openssl or an online encoder such as https://www.base64encode.org/.

As an example, if the credential uses ABCD as the key and 1234 as the secret, then the field's value is the base64 encoding of ABCD:1234, or QUJDRDoxMjM0

$ echo -n 'ABCD:1234' | openssl base64
QUJDRDoxMjM0

The Authorization header must appear as:
Authorization: Basic QUJDRDoxMjM0

It must be placed in the query in this format:

curl -i -X GET --url https://management.api.umbrella.com/v1/organizations \
--header 'Authorization: Basic %base64string%'

curl -i -X GET --url "https://management.api.umbrella.com/v1/organizations" \
 	--header 'Authorization: Basic QUJDRDoxMjM0'

Responses

Success

Example of a successful retrieval of your organization Id and name - HTTP 200

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

Errors

All errors return standard HTTP status code 4xx and 5xx responses.

HTTP Status Code
Error
Explanation

200

OK

Successful request

400

Validation error

Some field or property has not been filled out correctly

401

Unauthorized or Invalid authentication credentials

The authorization header is missing or the key:secret pair is invalid

403

Forbidden

Verify the endpoint

404

Resource Not Found

Verify the endpoint and any input field data

429

API rate limit exceeded

Wait before submitting another request

500

Error- This request could not be processed by the server

Try again later or contact support.

Data batch size

The API defaults to fetching lists of data in batches of 200.

Using the API

To review the available requests you can submit, refer to the API Reference.