Cisco Secure Access API, getting started

Getting Started with Secure Access

The Secure Access API provides a RESTful interface, described by version 3.x of the OpenAPI specification. The Secure Access API endpoints use JSON for all requests and responses.

Secure Access API Resources

Admin Resources

Key Admin API—Create, view, and manage Secure Access API keys.
Zero Trust User Devices API—Get the certificates for a user and device, and revoke the device certificates and remove the device on Secure Access.
VPN User Connections API—Get and update the organization's VPN user connections.
S3 Bucket Key Rotation API—Refresh the Cisco-managed S3 bucket key for the organization.
Third-Party Integrations API—Create, view, and manage the third-party applications and application credentials integrated in Secure Access.

Deployments Resources

Network Tunnel Groups and Regions API—Create, view, and manage the Network Tunnel Groups in the organization. View the regions for the Network Tunnel Groups.
Resource Connector Groups and Connectors API—Create, view, and manage the Connector Groups and Connectors in the organization.
Roaming Computers API—Get and manage the Roaming Computers in the organization.
Secure Web Gateway Device Settings API—Get and manage the Secure Web Gateway (SWG) override settings for the devices, which are registered with Secure Access.
Internal Domains API—Create, view, and manage the Internal Domains in the organization.
Sites API—Create, view, and manage the Sites in the organization.
Networks API—Create, view, and manage the Networks in the organization.
Internal Networks API—Create, view, and manage the Internal Networks in the organization.
Network Devices API—Create, view, and manage the Network Devices in the organization.
DNS Forwarders API—Create, view, and manage the DNS Forwarders in the organization.
Identities Registration API—Create, view, and manage the identity endpoints and security group tags (SGTs) in the organization.

Investigate Resources

Investigate API—Get the information about domains, IPs, and URLs observed by the Secure Access DNS resolvers.

Policies Resources

Destination Lists API—Create, view, and manage Destination Lists and destinations.
Application Lists API—Create, view, and manage Application Lists and internet applications.
Private Resources and Resource Groups API—Create, view, and manage Private Resources and Private Resource Groups in the organization.
Policy Rules and Rule Settings API—Create, view, and manage the Secure Access policy, access rules, and rules settings.
Network and Service Objects API—Create, view, and manage the Network Objects, Service Objects, and collections of these resources in groups for the organization.
Threat Intelligence Feeds API—Create, view, and manage the threat intelligence feeds for the third-party and custom security vendors.
Security Profiles API—Get the Security profiles for the organization.
Content Categories API—Get the Content Category settings for the organization.
Tenant Controls Profiles API—Get the Tenant Controls profiles for the organization.
Application Categories API—Get the Application Category settings for the organization.
IPS Profiles API—Create, view, and manage the Intrusion Prevention System (IPS) profiles and signatures for the organization.

Reports Resources

Reporting API—Get the Secure Access reports (activity, top threats, top destinations, top identities, top IPs, summary, threat types).
App Discovery API—Get reports about traffic in your organization to cloud applications, application protocols, and application categories.
Metering API–Get the metrics for the traffic between user devices and private and public resources, which are protected by Secure Access.
API Usage Reports API—Get the reports for the organization's API usage.

Base URI

The Secure Access API base URI is api.sse.cisco.com unless an API endpoint defines another base URI.

The API endpoints use the following API path scopes:

https://api.sse.cisco.com/admin/v2
https://api.sse.cisco.com/auth/v2
https://api.sse.cisco.com/deployments/v2
https://api.sse.cisco.com/investigate/v2
https://api.sse.cisco.com/policies/v2
https://api.sse.cisco.com/reports/v2

Authorization

The Secure Access Token Authorization API reads your API credentials and returns a Bearer token. Include your short-lived token in the Authorization header of each Secure Access API operation.

For information about creating your Secure Access API credentials, see Authentication.

Best Practices

The Secure Access Token Authorization API endpoint supports the OAuth 2.0 Client Credentials Flow. Secure Access only accepts API credentials (key and secret) created by a valid Secure Access administrative account. Secure Access can’t authenticate requests for deactivated accounts.

Note: A Secure Access OAuth 2.0 access token expires in one hour (3600 seconds). We recommend that you do not refresh an access token until the token is nearly expired.

Generate an API Access Token

The Secure Access Token Authorization API endpoint:

POST https://api.sse.cisco.com/auth/v2/token

Note: You can use any standards-based OAuth 2.0 client library to create a Secure Access API token.

Request

Run the curl or Python sample, providing your Secure Access API key and secret.

curl --user '<key>:<secret>' --request POST --url 'https://api.sse.cisco.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'

import requests
import json
import os
import time
from oauthlib.oauth2 import BackendApplicationClient
from oauthlib.oauth2 import TokenExpiredError
from requests_oauthlib import OAuth2Session
from requests.auth import HTTPBasicAuth

token_url = os.environ.get('TOKEN_URL') or 'https://api.sse.cisco.com/auth/v2/token'

# Export/Set the environment variables
client_id = os.environ.get('API_KEY')
client_secret = os.environ.get('API_SECRET')

class SecureAccessAPI:
    def __init__(self, url, ident, secret):
        self.url = url
        self.ident = ident
        self.secret = secret
        self.token = None

    def GetToken(self):
        auth = HTTPBasicAuth(self.ident, self.secret)
        client = BackendApplicationClient(client_id=self.ident)
        oauth = OAuth2Session(client=client)
        self.token = oauth.fetch_token(token_url=self.url, auth=auth)
        return self.token

# Exit out if the client_id, client_secret are not set
for var in ['API_SECRET', 'API_KEY']:
    if os.environ.get(var) == None:
        print("Required environment variable: {} not set".format(var))
        exit()

# Get token
api = SecureAccessAPI(token_url, client_id, client_secret)
print("Token: " + str(api.GetToken()))

Response Schema

Name	Type	Description
token_type	string	The type of access token.
access_token	string	The OAuth 2.0 access token.
expires_in	integer	The number of seconds that the token is valid.

Response

Sample response (200, OK):

{
   "token_type": "bearer",
   "access_token": "xxxxxx",
   "expires_in": 3600
}

Sample API Request

To make a Secure Access API request, substitute your Bearer token in the HTTP Authorization header.

For example:

curl -L --location-trusted --request GET --url 'https://api.sse.cisco.com/deployments/v2/regions' \
-H 'Authorization: Bearer %YourAcessToken%' \
-H 'Content-Type: application/json'

Expired Access Token

If you provide an expired API access token in the Authorization header of an API request, Secure Access responds with HTTP 400 (Bad Request) error:

{
    "error": "invalid_request"
}

To resolve the error condition, generate a new token through the Secure Access Token Authorization API.

Troubleshooting

For information about error conditions that may occur when you generate an access token or authorize a Secure Access API request, see Errors and Troubleshooting.

Pagination, Rate Limits, and Response Codes

For information about how to paginate the Secure Access API collections, see Pagination.
For information about the Secure Access API rate limits, see Rate Limits.
For information about the Secure Access HTTP response codes, see Errors and Troubleshooting.

OAuth 2.0 Scopes

For information about the Secure Access API OAuth 2.0 scopes, see Secure Access OAuth 2.0 Scopes.

Samples

We provide code examples, Postman collections, and curl samples to help you create your first Secure Access API request.