Cisco Secure Access API, OAuth 2.0 Scopes

Secure Access OAuth 2.0 Scopes

You can create API keys with Read-Only or Read/Write permissions for any number of Secure Access resources. Secure Access groups the resources into these scopes: admin, deployments, policies, and reports.

For information about creating your API credentials, see Secure Access API 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:create Create an API key. POST /admin/v2/apiKeys
admin.apikeys:read View an API key. GET /admin/v2/apiKeys
GET /admin/v2/apiKeys/{apiKeyId}
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

Zero Trust User Devices

Scope Description Endpoints
admin.ztna.devices:read View the certificates for a user device. GET /admin/v2/ztna/users/{userId}/devices/{deviceId}/certificates
admin.ztna.certificates:read View the device certificates for the user. GET /admin/v2/ztna/users/{userId}/deviceCertificates
admin.ztna.users:read View the counts and states of the user devices. GET /admin/v2/ztna/userSummaries
admin.ztna.enrollment:write Revoke certificates and remove the device on Secure Access. DELETE /admin/v2/ztna/users/{userId}/devices/{deviceId}

VPN User Connections

Scope Description Endpoints
admin.vpn:read View the VPN user connections. GET /admin/v2/vpn/userConnections
admin.vpn:write Update the VPN user connections. PUT /admin/v2/vpn/userConnections

S3 Bucket Key Rotation

Scope Description Endpoints
admin.iam:write Rotate the Cisco-managed S3 bucket key. POST /admin/v2/iam/rotateKey

Third-Party Integrations

Scope Description Endpoints
admin.integrations:read View the integrations of third-party applications and the application's credentials. GET /admin/v2/integrations
GET /admin/v2/integrationTypes
GET /admin/v2/integrations/{intId}
GET /admin/v2/integrations/{intId}/credentials/{credId}
GET /admin/v2/integrations/{intId}/credentials/{credId}/value
admin.integrations:write Create, update, or delete the integrated third-party applications and the application's credentials. POST /admin/v2/integrations
PUT /admin/v2/integrations
PATCH /admin/v2/integrations/{intId}
DELETE /admin/v2/integrations/{intId}
POST /admin/v2/integrations/{intId}/credentials

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:

Roaming Computers

Scope Description Endpoints
deployments.roamingcomputers:read View the roaming computers. GET /deployments/v2/roamingcomputers
GET /deployments/v2/roamingcomputers/{deviceId}
deployments.roamingcomputers:write Create, update, delete 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

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

Resource Connector Groups

Scope Description Endpoints
deployments.resourceconnectors:read View the resource connector groups. GET /deployments/v2/connectorGroups
GET /deployments/v2/connectorGroups/{id}
GET /deployments/v2/connectorGroups/counts
deployments.resourceconnectors:write Create, update, and delete the resource connector groups. POST /deployments/v2/connectorGroups
PUT /deployments/v2/connectorGroups/{id}
PATCH /deployments/v2/connectorGroups/{id}
DELETE /deployments/v2/connectorGroups/{id}

Resource Connectors

Scope Description Endpoints
deployments.resourceconnectors:read View the resource connector agents. GET /deployments/v2/connectorAgents
GET /deployments/v2/connectorAgents/{id}
GET /deployments/v2/connectorAgents/counts
deployments.resourceconnectors:write Update and delete the resource connector agents. PATCH /deployments/v2/connectorAgents/{id}
DELETE /deployments/v2/connectorAgents/{id}

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

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 domain. POST /deployments/v2/internaldomains
PUT /deployments/v2/internaldomains/{internalDomainId}
DELETE /deployments/v2/internaldomains/{internalDomainId}

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 Site. POST /deployments/v2/sites
PUT /deployments/v2/sites/{siteId}
DELETE /deployments/v2/sites/{siteId}

Networks

Scope Description Endpoints
deployments.networks:read View the networks. GET /deployments/v2/networks
GET /deployments/v2/networks/{networkId}
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}
deployments.internalnetworks:write Create, update, and delete the Internal Network. POST /deployments/v2/internalnetworks
PUT /deployments/v2/internalnetworks/{internalNetworkId}
DELETE /deployments/v2/internalnetworks/{internalNetworkId}

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}

DNS Forwarders

Scope Description Endpoints
deployments.dnsforwarders:read View the DNS Forwarders. GET /deployments/v2/dnsForwarders
GET /deployments/v2/dnsForwarders/{dnsForwardersId}
deployments.dnsforwarders:write Create, update, and delete the DNS Forwarder. POST /deployments/v2/dnsForwarders
PUT /deployments/v2/dnsForwarders/{dnsForwardersId}
DELETE /deployments/v2/dnsForwarders/{dnsForwardersId}

Identity Endpoints

Scope Description Endpoints
deployments.identities:read View the Identity Endpoints. GET /deployments/v2/identities/registrations/{type}
deployments.identities:write Create and update the Identity Endpoints. PUT /deployments/v2/identities/registrations/{type}

Investigate Scopes and Endpoints

Choose the investigate.investigate:read scope to retrieve the Investigate resources in your organization.

Choose the investigate.bulk:read scope to retrieve the Investigate resources in your organization for multiple domains.

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}.json
GET /investigate/v2/recommendations/name/{domain}
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:

Security Profiles

Scope Description Endpoints
policies.securityProfiles:read View the Security Profiles. GET /policies/v2/securityProfiles
GET /policies/v2/securityProfiles/{profileId}

Content Categories

Scope Description Endpoints
policies.contentCategories:read View the Content Category settings. GET /policies/v2/categorySettings

Tenant Controls Profiles

Scope Description Endpoints
policies.tenantControlsProfiles:read View the Tenant Controls Profiles. GET /policies/v2/tenantControls/profiles

Application Categories

Scope Description Endpoints
policies.applicationCategories:read View the Application Category settings. GET /policies/v2/applicationCategories

IPS Profiles

Scope Description Endpoints
policies.ipsconfig:read View the IPS profiles and the signatures. GET /policies/v2/ipsSignatureProfiles
GET /policies/v2/ipsSignatureProfiles/{id}
GET /policies/v2/ipsSignatureProfiles/{id}/signatures
policies.ipsconfig:write Create, update, and delete the IPS profiles and the signatures. POST /policies/v2/ipsSignatureProfiles
PATCH /policies/v2/ipsSignatureProfiles/{id}
DELETE /policies/v2/ipsSignatureProfiles/{id}

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 the destination lists. 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 the destination lists. GET /policies/v2/destinationlists/{destinationListId}/destinations
policies.destinations:write Create and delete the destinations in the destination lists. POST /policies/v2/destinationlists/{destinationListId}/destinations
DELETE /policies/v2/destinationlists/{destinationListId}/destinations/remove

Threat Intelligence Feeds

Scope Description Endpoints
policies.feeds:read View the threat feeds. GET /policies/v2/feeds
GET /policies/v2/feeds/{feedId}
policies.feeds:write Create, update, and delete the threat feed. POST /policies/v2/feeds
PUT /policies/v2/feeds/{feedId}
DELETE /policies/v2/feeds/{feedId}

Private Resource Groups

Scope Description Endpoints
policies.privateresources:read View the private resource groups. GET /policies/v2/privateResourceGroups
GET /policies/v2/privateResourceGroups/{id}
policies.privateresources:write Create, update, and delete the private resource groups. POST /policies/v2/privateResourceGroups
PUT /policies/v2/privateResourceGroups/{id}
DELETE /policies/v2/privateResourceGroups/{id}

Private Resources

Scope Description Endpoints
policies.privateresources:read View the private resources. GET /policies/v2/privateResources
GET /policies/v2/privateResources/{id}
policies.privateresources:write Create, update, and delete the private resources. POST /policies/v2/privateResources
PUT /policies/v2/privateResources/{id}
DELETE /policies/v2/privateResources/{id}

Network and Service Objects

Scope Description Endpoints
policies.objects.networkObjects:read View the network objects. GET /policies/v2/objects/networkObjects
GET /policies/v2/objects/networkObjects/references
GET /policies/v2/objects/networkObjects/{networkObjectId}
GET /policies/v2/objects/networkObjects/{networkObjectId}/references
GET /policies/v2/objects/unifiedNetworkObjects
policies.objects.networkObjects:write Create, update, and delete network objects. POST /policies/v2/objects/networkObjects
PUT /policies/v2/objects/networkObjects/{networkObjectId}
DELETE /policies/v2/objects/networkObjects/{networkObjectId}
POST /policies/v2/objects/networkObjects/upload
POST /policies/v2/objects/networkObjects/validate
Scope Description Endpoints
policies.objects.networkObjectGroups:read View the network object groups. GET /policies/v2/objects/networkObjectGroups
GET /policies/v2/objects/networkObjectGroups/references
GET /policies/v2/objects/networkObjectGroups/{networkObjectGroupId}
GET /policies/v2/objects/networkObjectGroups/{networkObjectGroupId}/references
GET /policies/v2/objects/unifiedNetworkObjects
policies.objects.networkObjectGroups:write Create, update, and delete network object groups. POST /policies/v2/objects/networkObjectGroups
PUT /policies/v2/objects/networkObjectGroups/{networkObjectGroupId}
DELETE /policies/v2/objects/networkObjectGroups/{networkObjectGroupId}
Scope Description Endpoints
policies.objects.serviceObjects:read View the service objects. GET /policies/v2/objects/serviceObjects
GET /policies/v2/objects/serviceObjects/references
GET /policies/v2/objects/serviceObjects/{serviceObjectId}
GET /policies/v2/objects/serviceObjects/{serviceObjectId}/references
GET /policies/v2/objects/unifiedServiceObjects
policies.objects.serviceObjects:write Create update, and delete service objects. POST /policies/v2/objects/serviceObjects
PUT /policies/v2/objects/serviceObjects/{serviceObjectId}
DELETE /policies/v2/objects/serviceObjects/{serviceObjectId}
POST /policies/v2/objects/serviceObjects/upload
POST /policies/v2/objects/serviceObjects/validate
Scope Description Endpoints
policies.objects.serviceObjectGroups:read View the service object groups. GET /policies/v2/objects/serviceObjectGroups
GET /policies/v2/objects/serviceObjectGroups/references
GET /policies/v2/objects/serviceObjectGroups/{serviceObjectGroupId}
GET /policies/v2/objects/serviceObjectGroups/{serviceObjectGroupId}/references
policies.objects.serviceObjectGroups:write Create, update, and delete service object groups. POST /policies/v2/objects/serviceObjectGroups
PUT /policies/v2/objects/serviceObjectGroups/{serviceObjectGroupId}
DELETE /policies/v2/objects/serviceObjectGroups/{serviceObjectGroupId}

Application Lists

Scope Description Endpoints
policies.applicationlists:read View the application lists. GET /policies/v2/applicationLists
GET /policies/v2/applications/usage
policies.applicationlists:write Create, update, and delete the application lists. POST /policies/v2/applicationLists
PUT /policies/v2/applicationLists/{applicationListId}
DELETE /policies/v2/applicationLists/{applicationListId}

Rules

Scope Description Endpoints
policies.rules:read View the rules. GET /policies/v2/rules
GET /policies/v2/rules/{ruleId}
GET /policies/v2/geolocations
policies.rules:write Create, update, and delete the rules. POST /policies/v2/rules
PUT /policies/v2/rules
PUT /policies/v2/rules/{ruleId}
DELETE /policies/v2/rules/{ruleId}

Rule Settings

Scope Description Endpoints
policies.settings:read View the rule settings. GET /policies/v2/settings
GET /policies/v2/settings/{settingName}
GET /policies/v2/settingTypes
GET /policies/v2/settingTypes/{settingName}
policies.settings:write Update and delete the rule settings. PUT /policies/v2/settings
PUT /policies/v2/settings/{settingName}
DELETE /policies/v2/settings/{settingName}

Reports Scopes and Endpoints

Choose the reports:read scope to retrieve the 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/ztna
GET /reports/v2/activity/decryption
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
GET /reports/v2/remote-access-events

Summaries By Rule

Scope Description Endpoints
reports.summariesByRule:read View the summaries by rule events. GET /reports/v2/summaries-by-rule/intrusion
GET /reports/v2/summaries-by-rule/hitcount
GET /reports/v2/summaries-by-rule/firewall-hitcount

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

Private Resources

Scope Description Endpoints
reports.privateResources:read View the events for the private resources. GET /reports/v2/top-resources
GET /reports/v2/top-resources/{type}
GET /reports/v2/requests-summary/appconnector-groups
GET /reports/v2/requests-by-appconnector
GET /reports/v2/requests-by-appconnector-group
GET /reports/v2/private-resource/detailed-stats-timerange
GET /reports/v2/private-resource/detailed-stats-identities
GET /reports/v2/private-resource/summary-stats
GET /reports/v2/unique-resources
GET /reports/v2/app-connectors/groups/detailed-stats-timerange
GET /reports/v2/app-connectors/groups/overloaded-count
GET /reports/v2/app-connectors/detailed-stats-timerange
GET /reports/v2/rules-activity

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}

Metering

Scope Description Endpoints
reports.usage.metrics:read View the usage metrics. GET /reports/v2/usage/metrics

API Usage

Scope Description Endpoints
reports.apiusage:read View the usage of the API keys. GET /reports/v2/apiUsage/requests
GET /reports/v2/apiUsage/responses
GET /reports/v2/apiUsage/keys
GET /reports/v2/apiUsage/summary