Cloud Security API, Umbrella OAuth 2.0, API key scopes
Umbrella 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 these scopes: admin, deployments, investigate, policies, and reports.
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 |
S3 Bucket Key Rotation
| Scope |
Description |
Endpoints |
admin.iam:write |
Rotate the Cisco-managed S3 bucket key. |
POST /admin/v2/iam/rotateKey |
Admin Scopes and Endpoints for Managed Organizations
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 for managed organizations includes these resources:
Password Reset
| Scope |
Description |
Endpoints |
admin.passwordreset:write |
Update the customer's password. |
POST /admin/v2/passwordResets/{customerId} |
Organizations
| Scope |
Description |
Endpoints |
admin.organizations:read |
View the organizations. |
GET /admin/v2/organizations |
Customers
| Scope |
Description |
Endpoints |
admin.customers:read |
View the customers. |
GET /admin/v2/providers/customers |
|
|
GET /admin/v2/providers/customers/{customerId} |
|
|
GET /admin/v2/providers/customers/{customerId}/accessRequests/{accessRequestId} |
|
|
GET /admin/v2/providers/customers/{customerId}/trialStrengths |
|
|
GET /admin/v2/providers/customers/packages |
|
|
GET /admin/v2/managed/customers |
|
|
GET /admin/v2/managed/customers/{customerId} |
admin.customers:write |
Create, update, and delete the customers. |
POST /admin/v2/providers/customers |
|
|
DELETE /admin/v2/providers/customers/{customerId} |
|
|
PUT /admin/v2/providers/customers/{customerId} |
|
|
PUT /admin/v2/providers/customers/{customerId}/trialconversions |
|
|
POST /admin/v2/providers/customers/{customerId}/accessRequests |
|
|
PUT /admin/v2/providers/customers/{customerId}/accessRequests/{accessRequestId} |
|
|
POST /admin/v2/managed/customers |
|
|
DELETE /admin/v2/managed/customers/{customerId} |
|
|
PUT /admin/v2/managed/customers/{customerId} |
Customer Search
| Scope |
Description |
Endpoints |
admin.customerSearch:read |
List the customers by the email addresses. |
GET /admin/v2/providers/customerAddresses |
Customer Deals
| Scope |
Description |
Endpoints |
admin.customerdeals:read |
View the customer deals. |
GET /admin/v2/providers/customerDeals/{dealId} |
admin.customerdeals:write |
Update the customer deals. |
PUT /admin/v2/providers/customerDeals/{dealId} |
Config
| Scope |
Description |
Endpoints |
admin.config:read |
View the configured logos, cnames, and contacts. |
GET /admin/v2/config/cnames |
|
|
GET /admin/v2/config/cnames/{cnameId} |
|
|
GET /admin/v2/config/contacts |
|
|
GET /admin/v2/config/contacts/{contactId} |
|
|
GET /admin/v2/config/logos/{logoId} |
|
|
GET /admin/v2/config/logos |
admin.config:write |
Create, update, and delete the configured logos, cnames, and contacts. |
POST /admin/v2/config/cnames |
|
|
PUT /admin/v2/config/cnames/{cnameId} |
|
|
DELETE /admin/v2/config/cnames/{cnameId} |
|
|
POST /admin/v2/config/contacts |
|
|
PUT /admin/v2/config/contacts/{contactId} |
|
|
DELETE /admin/v2/config/contacts/{contactId} |
|
|
POST /admin/v2/config/logos |
|
|
PUT /admin/v2/config/logos/{logoId} |
|
|
DELETE /admin/v2/config/logos/{logoId} |
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} |
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} |
Data Centers
| Scope |
Description |
Endpoints |
deployments.datacenters:read |
View the data centers for the network tunnels. |
GET /deployments/v2/datacenters |
Network Tunnels
| Scope |
Description |
Endpoints |
deployments.tunnels:read |
View the network tunnels. |
GET /deployments/v2/tunnels |
|
|
GET /deployments/v2/tunnels/{id} |
|
|
GET /deployments/v2/tunnels/{id}/policies |
|
|
GET /deployments/v2/tunnelsState |
|
|
GET /deployments/v2/tunnels/{id}/state |
|
|
GET /deployments/v2/tunnels/{id}/events |
|
|
GET /deployments/v2/tunnels/{id}/globalEvents/sourceIp/{ip} |
deployments.tunnels:write |
Create, update, and delete the network tunnels. |
POST /deployments/v2/tunnels |
|
|
PUT /deployments/v2/tunnels/{id} |
|
|
DELETE /deployments/v2/tunnels/{id} |
|
|
POST /deployments/v2/tunnels/{id}/keys |
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} |
OrgInfo for Roaming Computers
| Scope |
Description |
Endpoints |
deployments.roamingcomputersOrgInfo:read |
View the OrgInfo.json properties for roaming computers. |
GET /deployments/v2/roamingcomputers/orgInfo |
| Scope |
Description |
Endpoints |
deployments.tags:read |
View the tags. |
GET /deployments/v2/tags |
deployments.tags:write |
Create the tags. |
POST /deployments/v2/tags |
Tagged Devices
| Scope |
Description |
Endpoints |
deployments.tagDevices:read |
View the tagged devices. |
GET /deployments/v2/tags/{tagId}/devices |
deployments.tagDevices:write |
Create and delete the tagged devices. |
POST /deployments/v2/tags/{tagId}/devices |
|
|
DELETE /deployments/v2/tags/{tagId}/devices |
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} |
deployments.networkdevices:write |
Create, update, and delete the network devices. |
POST /deployments/v2/networkdevices |
|
|
PATCH /deployments/v2/networkdevices/{originId} |
|
|
DELETE /deployments/v2/networkdevices/{originId} |
Secure Web Gateway Device Settings
| Scope |
Description |
Endpoints |
deployments.devices.swg:read |
View the secure web gateway override settings on the devices. |
POST /deployments/v2/deviceSettings/SWGEnabled/list |
deployments.devices.swg:write |
Update and delete secure web gateway settings on the devices. |
POST /deployments/v2/deviceSettings/SWGEnabled/set |
|
|
POST /deployments/v2/deviceSettings/SWGEnabled/remove |
Investigate Scopes and Endpoints
Choose the investigate:read scope to retrieve the Investigate resources in your organization.
Choose the investigate.bulk:read scope to retrieve the Investigate bulk resources in your organization.
The Investigate OAuth 2.0 scope includes these resources:
Investigate
| Scope |
Description |
Endpoints |
investigate.investigate:read |
View the information about a domain. |
GET /investigate/v2/domains/categorization/{domain} |
|
|
GET /investigate/v2/domains/volume/{domain} |
|
|
GET /investigate/v2/recommendations/name/{domain}.json |
|
|
GET /investigate/v2/pdns/name/{domain} |
|
|
GET /investigate/v2/pdns/domain/{domain} |
|
|
GET /investigate/v2/pdns/ip/{ip} |
|
|
GET /investigate/v2/pdns/raw/{anystring} |
|
|
GET /investigate/v2/links/name/{domain} |
|
|
GET /investigate/v2/security/name/{domain} |
|
|
GET /investigate/v2/domains/risk-score/{domain} |
|
|
GET /investigate/v2/bgp_routes/ip/{ip}/as_for_ip.json |
|
|
GET /investigate/v2/bgp_routes/asn/{asn}/prefixes_for_asn.json |
|
|
GET /investigate/v2/whois/{domain} |
|
|
GET /investigate/v2/whois/{domain}/history |
|
|
GET /investigate/v2/whois/nameservers/{nameserver} |
|
|
GET /investigate/v2/whois/nameservers |
|
|
GET /investigate/v2/whois/emails/{email} |
|
|
GET /investigate/v2/whois/search/{searchField}/{regexExpression} |
|
|
GET /investigate/v2/search/{expression} |
|
|
GET /investigate/v2/topmillion |
|
|
GET /investigate/v2/samples/{destination} |
|
|
GET /investigate/v2/sample/{hash} |
|
|
GET /investigate/v2/sample/{hash}/artifacts |
|
|
GET /investigate/v2/sample/{hash}/connections |
|
|
GET /investigate/v2/sample/{hash}/behaviors |
|
|
GET /investigate/v2/timeline/{name} |
|
|
GET /investigate/v2/subdomains/{domain} |
Investigate Bulk
| Scope |
Description |
Endpoints |
investigate.bulk:read |
View the information about multiple domains. |
POST /investigate/v2/domains/categorization |
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/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} |
|
|
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 |
Granular Events
| Scope |
Description |
Endpoints |
reports.granularEvents:read |
View the granular 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 |
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} |
|
|
POST /reports/v2/identities |
App Discovery
| Scope |
Description |
Endpoints |
reports.appDiscovery:read |
View the application discovery events. |
GET /reports/v2/appDiscovery/applications |
|
|
GET /reports/v2/appDiscovery/applications/{applicationId} |
|
|
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/info |
reports.appDiscovery:write |
Update the label for the applications. |
PATCH /reports/v2/appDiscovery/applications |
|
|
PATCH /reports/v2/appDiscovery/applications/{applicationId} |
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 |
Reports Scopes and Endpoints for Managed Organizations
Choose the reports:read scope to retrieve the Reports resources in your managed organization.
Choose the reports:write scope to create, manage, or remove a Reports resource in your managed organization.
The Reports OAuth 2.0 scope for managed organizations includes these resources:
Utilities
| Scope |
Description |
Endpoints |
reports.utilities:read |
View the reference information for the reports. |
GET /reports/v2/providers/categories |
Customers
| Scope |
Description |
Endpoints |
reports.customers:read |
View the events for the customers. |
GET /reports/v2/providers/deployments |
|
|
GET /reports/v2/providers/requests-by-hour |
|
|
GET /reports/v2/providers/requests-by-timerange |
|
|
GET /reports/v2/providers/requests-by-org |
|
|
GET /reports/v2/providers/requests-by-category |
|
|
GET /reports/v2/providers/requests-by-destination |
|
|
GET /reports/v2/providers/category-requests-by-org |
|
|
GET /reports/v2/providers/category-requests-by-org |
|
|
GET /reports/v2/providers/consoles |
|
|
GET /reports/v2/providers/customers/downloadReportRequests |
reports.customers:write |
View the events by the request types. |
POST /reports/v2/providers/customers/{customerId}/securityReportRequests |