How to Migrate to the Umbrella API
Migrate your code and systems that integrate with the Umbrella Umbrella v1 APIs and Umbrella Reporting v2 API to the Umbrella API.
Prerequisites
- Full admin access to the Umbrella dashboard.
Step 1: Create New Umbrella API Credentials
- Create an Umbrella API key and secret. You must create new API credentials to connect to the Umbrella API. For more information, see Manage API Keys.
Step 2: Update Your Client Code
In your code, add an Umbrella API request to obtain an access token and replace the Umbrella v1 API URIs and Reporting v2 API URI with the Umbrella API endpoints. The Umbrella API supports the OAuth 2.0 Client Credentials Flow.
Note: Umbrella only accepts an API key and secret created by a valid Umbrella Admin user account. Umbrella cannot authenticate requests for deactivated or deleted Admin user accounts.
Create a request to the Umbrella Token Authorization API that includes your new Umbrella API key and secret. We recommend that you set up environment variables for your API key and API secret and use these environment variables in your code.
The Umbrella Token Authorization endpoint generates a short-lived Bearer token. The Umbrella API access token expires in one hour and you must generate a new token to continually access the Umbrella API. For information about creating an OAuth 2.0 client credentials flow in your code, see Cisco Umbrella Authorization Code Samples.
- For more information, see Getting Started with the Umbrella API.
Update the Umbrella v1 API URIs and Reporting v2 API URI to the Umbrella API endpoints. The Umbrella migration tables identify the Umbrella API key scopes and changes to the API URIs.
Migrate to Umbrella Token Authorization API
Unlike the Umbrella v1 APIs, which use Basic authentication, the Umbrella Reporting v2 API endpoints require a Bearer token generated by the Umbrella Management Authorization v2 API endpoint.
To connect to any of the next generation Umbrella API endpoints, you must generate an access token using the Umbrella Token Authorization API endpoint. The token provides access to resources that you defined as key scopes in your API key.
The Umbrella Token Authorization API endpoint is found at:
https://api.umbrella.com/auth/v2/token
In your code, update the Umbrella Management v2 Authorization API endpoint to the Umbrella Token Authorization API.
| Umbrella Management V2 Authorization API Endpoint | Umbrella Token Authorization API Endpoint |
|---|---|
| management.api.umbrella.com/auth/v2/oauth2/token | api.umbrella.com/auth/v2/token |
Migrate to Umbrella API Admin Endpoints
Update your Umbrella Management v1 API endpoints to the Umbrella API admin paths.
| Umbrella Management V1 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| management.api.umbrella.com/v1/organizations/{organizationId}/roles | api.umbrella.com/admin/v2/roles | admin.roles:read |
| management.api.umbrella.com/v1/organizations/{organizationId}/users | api.umbrella.com/admin/v2/users | admin.users:read, admin.users:write |
| management.api.umbrella.com/v1/msps/{mspId} | api.umbrella.com/admin/v2/managed/customers | admin.customers:read, admin.customers:write |
| management.api.umbrella.com/v1/serviceproviders/{serviceproviderId} | api.umbrella.com/admin/v2/providers/customers | admin.customers:read, admin.customers:write |
| management.api.umbrella.com/v1/organizations | api.umbrella.com/admin/v2/organizations | admin.organizations:read |
Migrate to Umbrella API Deployments Endpoints
Update your Management v1 API endpoints to the Umbrella API deployments paths.
| Umbrella Management V1 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| management.api.umbrella.com/v1/organizations/{organizationId}/networks | api.umbrella.com/deployments/v2/networks | deployments.networks:read, deployments.networks:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/internalnetworks | api.umbrella.com/deployments/v2/internalnetworks | deployments.internalnetworks:read, deployments.internalnetworks:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/internaldomains | api.umbrella.com/deployments/v2/internaldomains | deployments.internaldomains:read, deployments.internaldomains:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/virtualappliances | api.umbrella.com/deployments/v2/virtualappliances | deployments.virtualappliances:read, deployments.virtualappliances:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/roamingcomputers | api.umbrella.com/deployments/v2/roamingcomputers | deployments.roamingcomputers:read, deployments.roamingcomputers:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/sites | api.umbrella.com/deployments/v2/sites | deployments.sites:read, deployments.sites:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/tunnels | api.umbrella.com/deployments/v2/tunnels | deployments.tunnels:read, deployments.tunnels:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/tunnelsState | api.umbrella.com/deployments/v2/tunnelsState | deployments.tunnels:read |
| management.api.umbrella.com/v1/organizations/{organizationId}/policies | api.umbrella.com/deployments/v2/policies | deployments.policies:read, deployments.policies:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/networkdevices | api.umbrella.com/deployments/v2/networkdevices | deployments.networkdevices:read, deployments.networkdevices:write |
| management.api.umbrella.com/v1/service/tunnels/datacenters | api.umbrella.com/deployments/v2/datacenters | deployments.datacenters:read |
Migrate to Umbrella API Policies Endpoints
Update your Umbrella Management v1 API endpoints to the Umbrella API policies paths.
| Umbrella Management V1 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists | api.umbrella.com/policies/v2/destinationlists | policies.destinationlists:read, policies.destinationlists:write |
| management.api.umbrella.com/v1/organizations/{organizationId}/destinationlists/{destinationListId}/destinations | api.umbrella.com/policies/v2/destinationlists/{destinationListId}/destinations | policies.destinations:read, policies.destinations:write |
Migrate to Umbrella API Reports Endpoints
Update your Umbrella Reporting v2 API endpoints to the Umbrella API reports paths.
| Umbrella Reporting V2 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| reports.api.umbrella.com/v2/organizations/{organizationId}/activity | api.umbrella.com/reports/v2/activity | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-identities | api.umbrella.com/reports/v2/top-identities | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/identity-distribution | api.umbrella.com/reports/v2/identity-distribution | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-destinations | api.umbrella.com/reports/v2/top-destinations | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-categories | api.umbrella.com/reports/v2/top-categories | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-eventtypes | api.umbrella.com/reports/v2/top-eventtypes | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-dns-query-types | api.umbrella.com/reports/v2/top-dns-query-types | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-files | api.umbrella.com/reports/v2/top-files | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/total-requests | api.umbrella.com/reports/v2/total-requests | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-threats | api.umbrella.com/reports/v2/top-threats | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-threat-types | api.umbrella.com/reports/v2/top-threat-types | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-ips | api.umbrella.com/reports/v2/top-ips | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/top-urls | api.umbrella.com/reports/v2/top-urls | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/summary | api.umbrella.com/reports/v2/summary | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/summaries-by-category | api.umbrella.com/reports/v2/summaries-by-category | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/summaries-by-destination | api.umbrella.com/reports/v2/summaries-by-destination | reports.aggregations:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/summaries-by-rule/intrusion | api.umbrella.com/reports/v2/summaries-by-rule/intrusion | reports.aggregations:read |
| Umbrella Reporting V2 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| reports.api.umbrella.com/v2/organizations/{organizationId}/requests-by-hour | api.umbrella.com/reports/v2/requests-by-hour | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/requests-by-timerange | api.umbrella.com/reports/v2/requests-by-timerange | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/categories-by-hour | api.umbrella.com/reports/v2/categories-by-hour | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/categories-by-timerange | api.umbrella.com/reports/v2/categories-by-timerange | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/deployment-status | api.umbrella.com/reports/v2/deployment-status | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/bandwidth-by-hour | api.umbrella.com/reports/v2/bandwidth-by-hour | reports.granularEvents:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/bandwidth-by-timerange | api.umbrella.com/reports/v2/bandwidth-by-timerange | reports.granularEvents:read |
| Umbrella Reporting V2 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| reports.api.umbrella.com/v2/organizations/{organizationId}/applications | api.umbrella.com/reports/v2/applications | reports.utilities:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/categories | api.umbrella.com/reports/v2/categories | reports.utilities:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/categories | api.umbrella.com/reports/v2/providers/categories | reports.utilities:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/threat-types | api.umbrella.com/reports/v2/threat-types | reports.utilities:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/threat-names | api.umbrella.com/reports/v2/threat-names | reports.utilities:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/remote-access-events | api.umbrella.com/reports/v2/remote-access-events | reports.utilities:read |
| reports.api.umbrella.com/v2/organizations/{organizationId}/identities | api.umbrella.com/reports/v2/identities | reports.utilities:read, reports.utilities:write |
Migrate to Umbrella API Reports Endpoints for Managed Organizations
Update your Umbrella Reporting v2 API endpoints for managed organizations to the Umbrella API reports paths.
| Umbrella Reporting V2 API Endpoint | Umbrella API Endpoint | Umbrella API Key Scopes |
|---|---|---|
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/deployments | api.umbrella.com/reports/v2/providers/deployments | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/requests-by-hour | api.umbrella.com/reports/v2/providers/requests-by-hour | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/requests-by-timerange | api.umbrella.com/reports/v2/providers/requests-by-timerange | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/requests-by-org | api.umbrella.com/reports/v2/providers/requests-by-org | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/requests-by-category | api.umbrella.com/reports/v2/providers/requests-by-category | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/category-requests-by-org | api.umbrella.com/reports/v2/providers/category-requests-by-org | reports.customers:read |
| reports.api.umbrella.com/v2/providers/{mspOrganizationId}/requests-by-destination | api.umbrella.com/reports/v2/providers/requests-by-destination | reports.customers:read |
Step 3: Test Your Clients
- Test your client code. We provide code examples, Postman collections, and
curlsamples that describe how to create requests to the Umbrella API.