Overview

The Umbrella API was released in September 2022, providing a user-friendly and secure platform that enables users to build on, extend, and integrate with Umbrella.

The Umbrella API endpoints are hosted on api.umbrella.com, with grouped paths per use case. API keys can be managed both in the Umbrella dashboard, under Admin -> API keys, and programmatically with the KeyAdmin API. Each key can be granularly configured with multiple scopes grouped under five primary use cases:

• Admin API endpoints enable you to provision and manage Umbrella API keys and users, view roles, and manage customers for providers and managed providers.
• Auth API endpoints enable you to authorize other services’ integrations with the Umbrella platform.
• Deployments API endpoints enable you to provision, monitor and manage networks and other various entities, and secure them by configuring them in your existing Umbrella policies.
• Policies API endpoints enable you to provision and manage destination lists and the destinations per list.
• Reports API endpoints enable you to read and audit real-time security information about your deployments. The Umbrella App Discovery API provides insights into your cloud-based applications.

In this article we will try to collect activity search reports via API.

Procedure:

• From dashboard navigate to Admin > API Keys > choose API Keys, click add.Choose Reports from Key scope and click "Create Key":

• Admins can adjust the level of access per scope between Read / Write and Read-Only, depending on the intended use of each API key, while the API keys can be configured to expire on a pre-defined date. You are required to collect the API key/secret at this step, as they are currently visible, and they won't show up afterwards. 
• The API credentials generate API access tokens which are valid for 60 minutes. This procedure supports the OAuth 2.0 client credentials flow. In Umbrella multi-org or service provider environments, parent-org API credentials can be used to generate access tokens with the same scopes for a child org specified during the authorization process.

Postman Procedure

• At the first you require to create OAuth 2.0 access token. The Umbrella API auth paths begin with https://api.umbrella.com/auth/v2. Upon the submission of a POST query and user API key as username and API password as password, an Access Token will be generated.

At this step, you are required to collect Access Token. Now you can retrieve information with the Access Token.

• You are required to select GET method and enter both your API path (including the parameter you require) and Access Token. In this example, I intend to retrieve 100 reports from the activity search exclusively for DNS traffic for last 7 days.

• In another example, I attempted to extract 1000 reports from activity search, exclusively for DNS traffic for last 7 days, specifically for the "gsa.apple.com" domain.

• You can consult Request Query Parameters to discover additional parameters you can use in your API query.
• Note: If an HTTP client request does not originate from the same continent as the location of the Umbrella data warehouse, the Umbrella server responds with 302 Found.
  To automatically redirect HTTP requests and preserve the HTTP Authorization header, you can set additional flags or enable a redirect setting.
  curl: You must pass the -L or --location, and --location-trusted flags to redirect the curl HTTP request and retain the Authorization header.

Postman: Within the Postman environment, navigate to an API and choose a GET method. Navigate to Settings. Enable Follow Authorization header to preserve the Authorization header for redirect requests.

Responses