Umbrella Management API, Network Devices API: Getting Started, Rate Limits, Response Codes

Getting Started

The Umbrella Management API and the Umbrella Network Devices and Policies API follow RESTful principles and use JSON for requests and responses.

Base URI

The Umbrella Destination Lists API begins with the following base URI:

https://management.api.umbrella.com/v1

Authentication

The Umbrella Management API and Umbrella Network Devices and Policies API use HTTP Basic authentication. Include your Umbrella Management API credentials in a request to the Umbrella Management API. Umbrella Network Devices API requests require your Network Devices API key and secret. For more information about creating a legacy Umbrella API key, see Authentication.

Authorization

To create an API request, substitute your encoded credentials in the HTTP Authorization header.

Encode Your API Credentials

You can run one of the sample scripts to encode your credentials.

echo -n '<key>:<secret>' | openssl base64

[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('<key>:<secret>'))

echo '<key>:<secret>' | python -m base64

Request

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

Get Organization Information

You can locate your organization ID in the Umbrella URL:

https://dashboard.umbrella.com/o/<organizationId>/

To get your organization information, create a request to the Umbrella Network Devices and Policies API /organizations endpoint and include your Umbrella Network Devices API credentials. For more information, see Get Organization ID and Name.

Umbrella Policies

You create an Umbrella policy through the Umbrella dashboard and add an identity to a policy. The Umbrella Network Devices and Policies API provides endpoints to list your Umbrella policies, and add or remove an identity from a DNS or Web policy. For more information, see Add Identity to Umbrella Policy.

Pagination

The Umbrella Management API endpoints that list a collection also support pagination. You can set the limit and page request query parameters for these endpoints.

If the limit parameter is not set, Umbrella returns up to 200 records per request. If not specified, the page offset starts at the beginning of the collection. The default page value is 1.

Pagination does not apply to the following endpoints:

• /organizations/{organizationId}/users
• /organizations/{organizationId}/roles
• /organizations/{organizationId}/virtualappliances

Pagination defined by endpoint:

• /organizations/{organizationId}/networks
  • Maximum batch size is 1000 records
• /organizations/{organizationId}/roamingcomputers
  • Maximum batch size is 200 records
• /organizations/{organizationId}/destinationlists/{destinationListId}/destinations
  • Maximum batch size is 100 records

Use the limit query parameter to set the maximum number of records returned for the request.

For example:

curl -i GET https://management.api.umbrella.com/v1/msps/{MSPId}/customers?limit=100 \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

To specify an offset in the collection, set the page query parameter. For example:

curl -i GET https://management.api.umbrella.com/v1/msps/{MSPId}/customers?page=2 \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Rate Limits

The Umbrella Management API requests are rate limited. Rate limits apply to individual API keys. You can create requests following these guidelines:

• 5 requests per second
• 14 requests per minute
• 350 requests per 30 minutes

Response Codes

The Umbrella Management API endpoints use HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with Umbrella's servers.