## Unlisted page

This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

---

## On this page

This documentation for the Cisco Umbrella integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate Cisco Umbrella, visit our [connection instructions](https://docs.datagrail.io/docs/integrations/connection-instructions/cisco_umbrella).

## Version

This integration utilizes the Cisco Umbrella Secure Access Reports API **v2**.

## Base URL

The base URL used for all Cisco Umbrella API endpoints contains the **Region (us | eu)**:

```
https://api.sse.cisco.com/reports.region/v2
```

---

## Authentication & Authorization

The DataGrail Cisco Umbrella integration connects using **OAuth 2.0** with the following credentials: **API Key** and **Key Secret**.

**Sensitive Credentials**  
Publicly exposing your API credentials can allow unauthorized access to Cisco Umbrella API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

Cisco Umbrella connects via **OAuth 2.0 Client Credentials**.

To obtain an access token, DataGrail sends a `POST` request to the token endpoint using:
- `Content-Type: application/x-www-form-urlencoded`
- `grant_type=client_credentials`
- `Authorization: Basic base64(API Key:Key Secret)`

#### Endpoints Utilized

DataGrail uses the following endpoints to authorize and test the connection:

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/appDiscovery/applications` | Validate credentials |  |
| POST | `https://api.umbrella.com/auth/v2/token` | Get access token (OAuth 2.0 Client Credentials) |  |

## Limits

Limits in Cisco Umbrella are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an `HTTP 429 Too Many Requests` error is returned. Requests succeed again after enough requests have emptied out of the bucket.

- DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
- DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

---

## Capabilities

### System Detection

DataGrail provides continuous system detection, delivering a real-time inventory of your data assets.

#### Data Interactions

DataGrail's **System Detection** process runs once daily and performs the following actions:
1. List **Applications** via App Discovery.
2. For applications with a non-zero `identitiesCount`, fetch application identities (up to **20**) to enrich the system with detected owners. If the identities enrichment request fails, system detection continues without owner enrichment for that application.

#### Endpoints Utilized

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/appDiscovery/applications` | List applications (App Discovery) |  |
| GET | `/appDiscovery/applications/application_id/identities` | List identities for an application (owner enrichment) |  |

---

Need help?

If you have any questions, please reach out to your dedicated Account Manager or contact us at [support@datagrail.io](mailto:support@datagrail.io).

_Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material._