OAuth 2.0 Scopes
You can create API keys with Read-Only or Read/Write permissions for any number of Umbrella resources. Umbrella groups the resources into the admin, deployments, investigate, policies, and reports scopes.
For information about creating your API credentials, see Authentication.
Admin Scopes and Endpoints
Choose the admin:read scope to retrieve the Admin resources in your organization.
Choose the admin:write scope to create, manage, or remove an Admin resource in your organization.
The Admin OAuth 2.0 scope includes these resources:
ApiKeys
| Scope |
Description |
Endpoints |
admin.apikeys:delete |
Delete an API key. |
DELETE /admin/v2/apiKeys/{apiKeyId} |
admin.apikeys:update |
Update an API key. |
PATCH /admin/v2/apiKeys/{apiKeyId} |
admin.apikeys:refresh |
Refresh an API key. |
POST /admin/v2/apiKeys/{apiKeyId}/refresh |
admin.apikeys:read |
View an API key. |
GET /admin/v2/apiKeys |
|
|
GET /admin/v2/apiKeys/{apiKeyId} |
admin.apikeys:create |
Create an API key. |
POST /admin/v2/apiKeys |
Users
| Scope |
Description |
Endpoints |
admin.users:read |
View the user accounts. |
GET /admin/v2/users |
|
|
GET /admin/v2/users/{userId} |
admin.users:write |
Create and delete the user accounts. |
POST /admin/v2/users |
|
|
DELETE /admin/v2/users/{userId} |
Roles
| Scope |
Description |
Endpoints |
admin.roles:read |
View the user roles. |
GET /admin/v2/roles |
Deployments Scopes and Endpoints
Choose the deployments:read scope to retrieve the Deployments resources in your organization.
Choose the deployments:write scope to create, manage, or remove a Deployments resource in your organization.
The Deployments OAuth 2.0 scope includes these resources:
Networks
| Scope |
Description |
Endpoints |
deployments.networks:read |
View the networks. |
GET /deployments/v2/networks |
|
|
GET /deployments/v2/networks/{networkId} |
|
|
GET /deployments/v2/networks/{networkId}/policies |
deployments.networks:write |
Create, update, and delete the networks. |
POST /deployments/v2/networks |
|
|
PUT /deployments/v2/networks/{networkId} |
|
|
DELETE /deployments/v2/networks/{networkId} |
Network Tunnel Groups
| Scope |
Description |
Endpoints |
deployments.networktunnelgroups:read |
View the network tunnel groups. |
GET /deployments/v2/networktunnelgroups |
|
|
GET /deployments/v2/networktunnelgroups/{id} |
|
|
GET /deployments/v2/networktunnelgroups/{id}/state |
|
|
GET /deployments/v2/networktunnelgroups/{id}/networktunnelhubs/{hub_id}/peers/{peer_id}/state |
|
|
GET /deployments/v2/networktunnelgroupsstate |
deployments.networktunnelgroups:write |
Create, update, and delete the network tunnel groups. |
POST /deployments/v2/networktunnelgroups |
|
|
PATCH /deployments/v2/networktunnelgroups/{id} |
|
|
DELETE /deployments/v2/networktunnelgroups/{id} |
Regions
| Scope |
Description |
Endpoints |
deployments.regions:read |
View the regions. |
GET /deployments/v2/regions |
Internal Networks
| Scope |
Description |
Endpoints |
deployments.internalnetworks:read |
View the internal networks. |
GET /deployments/v2/internalnetworks |
|
|
GET /deployments/v2/internalnetworks/{internalNetworkId} |
|
|
GET /deployments/v2/internalnetworks/{internalNetworkId}/policies |
deployments.internalnetworks:write |
Create, update, and delete the internal networks. |
POST /deployments/v2/internalnetworks |
|
|
PUT /deployments/v2/internalnetworks/{internalNetworkId} |
|
|
DELETE /deployments/v2/internalnetworks/{internalNetworkId} |
Internal Domains
| Scope |
Description |
Endpoints |
deployments.internaldomains:read |
View the internal domains. |
GET /deployments/v2/internaldomains |
|
|
GET /deployments/v2/internaldomains/{internalDomainId} |
deployments.internaldomains:write |
Create, update, and delete the internal domains. |
POST /deployments/v2/internaldomains |
|
|
PUT /deployments/v2/internaldomains/{internalDomainId} |
|
|
DELETE /deployments/v2/internaldomains/{internalDomainId} |
Roaming Computers
| Scope |
Description |
Endpoints |
deployments.roamingcomputers:read |
View the roaming computers. |
GET /deployments/v2/roamingcomputers |
|
|
GET /deployments/v2/roamingcomputers/{deviceId} |
deployments.roamingcomputers:write |
View, update, and delete the roaming computers. |
PUT /deployments/v2/roamingcomputers/{deviceId} |
|
|
DELETE /deployments/v2/roamingcomputers/{deviceId} |
Policies
| Scope |
Description |
Endpoints |
deployments.policies:read |
View the policies for the deployments. |
GET /deployments/v2/policies |
deployments.policies:write |
Update and delete the policies for the deployments. |
PUT /deployments/v2/policies/{policyId}/identities/{originId} |
|
|
DELETE /deployments/v2/policies/{policyId}/identities/{originId} |
Sites
| Scope |
Description |
Endpoints |
deployments.sites:read |
View the sites. |
GET /deployments/v2/sites |
|
|
GET /deployments/v2/sites/{siteId} |
deployments.sites:write |
Create, update, and delete the sites. |
POST /deployments/v2/sites |
|
|
PUT /deployments/v2/sites/{siteId} |
|
|
DELETE /deployments/v2/sites/{siteId} |
Virtual Appliances
| Scope |
Description |
Endpoints |
deployments.virtualappliances:read |
View the virtual appliances. |
GET /deployments/v2/virtualappliances |
|
|
GET /deployments/v2/virtualappliances/{virtualApplianceId} |
deployments.virtualappliances:write |
Update and delete the virtual appliances. |
PUT /deployments/v2/virtualappliances/{virtualApplianceId} |
|
|
DELETE /deployments/v2/virtualappliances/{virtualApplianceId} |
Network Devices
| Scope |
Description |
Endpoints |
deployments.networkdevices:read |
View the network devices. |
GET /deployments/v2/networkdevices |
|
|
GET /deployments/v2/networkdevices/{originId} |
|
|
GET /deployments/v2/networkdevices/{originId}/policies |
deployments.networkdevices:write |
Create, update, and delete the network devices. |
POST /deployments/v2/networkdevices |
|
|
DELETE /deployments/v2/networkdevices/{originId} |
Policies Scopes and Endpoints
Choose the policies:read scope to retrieve the Policies resources in your organization.
Choose the policies:write scope to create, manage, or remove a Policies resource in your organization.
The Policies OAuth 2.0 scope includes these resources:
Destination Lists
| Scope |
Description |
Endpoints |
policies.destinationLists:read |
View the destination lists. |
GET /policies/v2/destinationlists |
|
|
GET /policies/v2/destinationlists/{destinationListId} |
policies.destinationLists:write |
Create, update, and delete a destination list. |
POST /policies/v2/destinationlists |
|
|
PATCH /policies/v2/destinationlists/{destinationListId} |
|
|
DELETE /policies/v2/destinationlists/{destinationListId} |
Destinations
| Scope |
Description |
Endpoints |
policies.destinations:read |
View the destinations in a destination list. |
GET /policies/v2/destinationlists/{destinationListId}/destinations |
policies.destinations:write |
Add and delete destinations in a destination list. |
POST /policies/v2/destinationlists/{destinationListId}/destinations |
|
|
DELETE /policies/v2/destinationlists/{destinationListId}/destinations/remove |
Reports Scopes and Endpoints
Choose the reports:read scope to retrieve Reports resources in your organization.
Choose the reports:write scope to create, manage, or remove a Reports resource in your organization.
The Reports OAuth 2.0 scope includes these resources:
Aggregations
| Scope |
Description |
Endpoints |
reports.aggregations:read |
View the aggregated events. |
GET /reports/v2/activity |
|
|
GET /reports/v2/activity/dns |
|
|
GET /reports/v2/activity/proxy |
|
|
GET /reports/v2/activity/firewall |
|
|
GET /reports/v2/activity/intrusion |
|
|
GET /reports/v2/activity/ip |
|
|
GET /reports/v2/activity/amp-retrospective |
|
|
GET /reports/v2/top-identities |
|
|
GET /reports/v2/top-identities/{type} |
|
|
GET /reports/v2/identity-distribution |
|
|
GET /reports/v2/identity-distribution/{type} |
|
|
GET /reports/v2/top-destinations |
|
|
GET /reports/v2/top-destinations/{type} |
|
|
GET /reports/v2/top-urls |
|
|
GET /reports/v2/top-categories |
|
|
GET /reports/v2/top-categories/{type} |
|
|
GET /reports/v2/top-eventtypes |
|
|
GET /reports/v2/top-dns-query-types |
|
|
GET /reports/v2/top-files |
|
|
GET /reports/v2/total-requests |
|
|
GET /reports/v2/total-requests/{type} |
|
|
GET /reports/v2/top-threats |
|
|
GET /reports/v2/top-threats/{type} |
|
|
GET /reports/v2/top-threat-types |
|
|
GET /reports/v2/top-threat-types/{type} |
|
|
GET /reports/v2/top-ips |
|
|
GET /reports/v2/top-ips/internal |
|
|
GET /reports/v2/summary |
|
|
GET /reports/v2/summary/{type} |
|
|
GET /reports/v2/summaries-by-category |
|
|
GET /reports/v2/summaries-by-category/{type} |
|
|
GET /reports/v2/summaries-by-destination |
|
|
GET /reports/v2/summaries-by-destination/{type} |
Granular Events
| Scope |
Description |
Endpoints |
reports.granularEvents:read |
View the granular events. |
GET /reports/v2/requests-by-hour |
|
|
GET /reports/v2/requests-by-hour/{type} |
|
|
GET /reports/v2/requests-by-timerange |
|
|
GET /reports/v2/requests-by-timerange/{type} |
|
|
GET /reports/v2/categories-by-hour |
|
|
GET /reports/v2/categories-by-hour/{type} |
|
|
GET /reports/v2/categories-by-timerange |
|
|
GET /reports/v2/categories-by-timerange/{type} |
|
|
GET /reports/v2/deployment-status |
|
|
GET /reports/v2/bandwidth-by-hour |
|
|
GET /reports/v2/bandwidth-by-timerange |
Summaries By Rule
| Scope |
Description |
Endpoints |
reports.summariesByRule:read |
View the summaries by rules events. |
GET /reports/v2/summaries-by-rule/intrusion |
Utilities
| Scope |
Description |
Endpoints |
reports.utilities:read |
View the reference information for the reports. |
GET /reports/v2/applications |
|
|
GET /reports/v2/categories |
|
|
GET /reports/v2/identities |
|
|
GET /reports/v2/identities/{identityid} |
|
|
GET /reports/v2/threat-types |
|
|
GET /reports/v2/threat-types/{threattypeid} |
|
|
GET /reports/v2/threat-names |
|
|
GET /reports/v2/threat-names/{threatnameid} |
reports.utilities:write |
View the reference information for multiple deployments. |
POST /reports/v2/identities |
App Discovery
| Scope |
Description |
Endpoints |
reports.appDiscovery:read |
View the app discovery events. |
GET /reports/v2/appDiscovery/applications |
|
|
GET /reports/v2/appDiscovery/applications/{applicationId}/risk |
|
|
GET /reports/v2/appDiscovery/applications/{applicationId}/identities |
|
|
GET /reports/v2/appDiscovery/applications/{applicationId}/attributes |
|
|
GET /reports/v2/appDiscovery/protocols |
|
|
GET /reports/v2/appDiscovery/protocols/{protocolId} |
|
|
GET /reports/v2/appDiscovery/protocols/{protocolId}/identities |
|
|
GET /reports/v2/appDiscovery/applicationCategories |
|
|
GET /reports/v2/appDiscovery/applications/{applicationId} |
reports.appDiscovery:write |
Update the label for the applications. |
PATCH /reports/v2/appDiscovery/applications |
API Usage
| Scope |
Description |
Endpoints |
reports.apiusage:read |
View the API key usage. |
GET /reports/v2/apiUsage/requests |
|
|
GET /reports/v2/apiUsage/responses |
|
|
GET /reports/v2/apiUsage/keys |
|
|
GET /reports/v2/apiUsage/summary |