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.

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 is a 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 Umbrella API authentication, see About the Umbrella Console API endpoints.

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

Generate an API Key

  1. In the Umbrella dashboard, navigate to Admin > API Keys and click Create.
    In one of the service provider consoles (Multi-org, MSP, or MSSP), navigate to Settings > API Keys and click Generate API Key.
  2. Choose an API and click Create.
    Note: If you select Legacy Network Devices, Umbrella generates an API Token rather than a secret and key.
  1. Copy your key and secret.
    Keep your secret in a secure location for future retrieval. Once you close this page you cannot retrieve your secret.


You have only one opportunity to copy your secret. Secrets are not stored within Umbrella and cannot be resurfaced after its initial creation.

  1. Click the acknowledgment checkbox to confirm that you understand that the secret cannot be regenerated and then click Close.
  2. To generate a new key and secret, click Refresh for 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

Allow cURL to generate the header, substituting your numeric Umbrella MSP ID for [msp_id] (for example, ""

curl -u 'key:secret'  --url "[msp_id]/customers"
curl -i -X GET --url "[msp_id]/customers" \
 	--user 'key:secret'

We recommend generating your own header. You can use a base64 encoding tool such as openssl or an online encoder such as

For 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

The Authorization header must appear as: Authorization: Basic QUJDRDoxMjM0

It must be placed in the query in this format:

curl -i -X GET --url[msp_id]/customers \
--header 'Authorization: Basic %base64string%'

curl -i -X GET --url "[msp_id]/customers" \
 	--header 'Authorization: Basic QUJDRDoxMjM0'



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

        "organizationId": 123456789,
        "name": "Your Organization Name"


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

HTTP Status Code



Successful request


Validation error

Some field or property has not been filled out correctly


Unauthorized or Invalid authentication credentials

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



Verify the endpoint


Resource Not Found

Verify the endpoint and any input field data


API rate limit exceeded

Wait before submitting another request


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.

Updated 7 months ago

Getting Started with the Management API

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

Suggested Edits are limited on API Reference Pages

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