Umbrella Reporting v2 API: list Activities, Summary

Getting Started

The Umbrella Reporting v2 API follows RESTful principles and uses JSON for requests and responses.

Base URI

The Umbrella Reporting v2 API begins with the following base URI:

https://reports.api.umbrella.com/v2

Authentication

The Umbrella Reporting v2 API supports the OAuth 2.0 client credentials flow. Include your Umbrella Reporting API key and secret in a request to the Umbrella Management API token authorization endpoint and generate an access token. For information about creating a legacy Umbrella API key, see Authentication.

Authorization

The Umbrella Reporting v2 API requests require an Authorization header and use Bearer token authentication.

Create an API Access Token

With your Umbrella Reporting API key and secret, create an HTTP POST request to the Umbrella Management API authorization endpoint:

https://management.api.umbrella.com/auth/v2/oauth2/token

The Umbrella Management API authorization endpoint supports the OAuth 2.0 Client Credentials Flow.

Note: Umbrella only accepts Reporting API credentials (key and secret) created by a valid Umbrella Admin user account. Umbrella cannot authenticate requests for deactivated or deleted Admin user accounts.

Access Token Best Practices

You can use any standards-based OAuth 2.0 client library to create the Umbrella Reporting v2 API access token. We provide code samples that integrate the OAuth 2.0 client credentials token flow with an Umbrella Reporting v2 API request. For information about the code samples, see Cisco Umbrella Client Samples.

Note: An Umbrella Reporting API OAuth 2.0 access token expires in one hour (3600 seconds). We recommend that you do not refresh an access token until the token is nearly expired.

Request

Create an OAuth 2.0 access token.

POST auth/v2/oauth2/token

curl -i --user "<key>:<secret>" -X POST https://management.api.umbrella.com/auth/v2/oauth2/token

# Prerequisites
# pip install requests
# pip install requests requests_oauthlib
import requests
import json
import os
import time
from oauthlib.oauth2 import BackendApplicationClient
from oauthlib.oauth2 import TokenExpiredError
from requests_oauthlib import OAuth2Session
from requests.auth import HTTPBasicAuth

token_url = os.environ.get('TOKEN_URL') or 'https://management.api.umbrella.com/auth/v2/oauth2/token'
# Export/Set the environment variables
client_id = os.environ.get('API_KEY')
client_secret = os.environ.get('API_SECRET')

class UmbrellaAPI:
    def __init__(self, url, ident, secret):
        self.url = url
        self.ident = ident
        self.secret = secret
        self.token = None

    def GetToken(self):
        auth = HTTPBasicAuth(self.ident, self.secret)
        client = BackendApplicationClient(client_id=self.ident)
        oauth = OAuth2Session(client=client)
        self.token = oauth.fetch_token(token_url=self.url, auth=auth)
        return self.token

# Exit out if the client_id, client_secret are not set.
for var in ['API_SECRET', 'API_KEY']:
    if os.environ.get(var) == None:
        print("Required environment variable: {} not set".format(var))
        exit()

# Get token and make an API request
api = UmbrellaAPI(token_url, client_id, client_secret)
print("Token: " + str(api.GetToken()))

MSP Child Organization Request

You must create separate access tokens for each managed service provider (MSP) child organization. Use your Reporting API credentials to generate an access token for a child organization.

Note: You must include the child organizationId in the X-Umbrella-OrgId request header to generate the access token for the MSP child organization.

For example:

curl -i --user "<key>:<secret>" -X POST https://management.api.umbrella.com/auth/v2/oauth2/token \
-H 'X-Umbrella-OrgID: <child organizationId>'

Response

Sample response (200, OK):

{
   "token_type": "bearer",
   "access_token": "xxxxxx",
   "expires_in": 3600
}

Add Token to Authorization Header

To create an API request, substitute your Bearer token in the HTTP Authorization header.

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/activity?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer %YourAccessToken%' \
-H 'Content-Type: application/json'

Pagination

You can control the number of records in the result set and manage how to read the collection with the limit and offset query parameters.

The Umbrella Reporting v2 API endpoints provide various query parameters to filter and customize requests. For more information, see Umbrella Reporting v2 API Request Query Parameters.

Rate Limits

The Umbrella Reporting API endpoints are rate limited. Rate limits apply to all Reporting API requests from an organization. You can create API requests following these general guidelines:

• 5 requests per second

Response Codes

The Umbrella Reporting v2 API uses 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.