Cisco Secure Access China API, getting started

Getting Started

The Cisco Secure Access China 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 unless noted.

Secure Access API Resources

Admin Resources

• Key Admin API—Create and manage Secure Access API keys.
• VPN User Connections API—Get and update the organization's VPN user connections.

Deployments Resources

• Network Tunnel Groups and Regions API—Create, get, and manage the Network Tunnel Groups in the organization. View the regions for the Network Tunnel Groups.
• 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.

Policies Resources

• Destination Lists API—Create, get, and manage Destination Lists and destinations.
• Private Resources and Resource Groups API—Create, get, and manage Private Resources and Private Resource Groups in the organization.
• Policy Rules API—Create and manage the Secure Access policy, access rules, rules settings, and application lists.
• Network and Service Objects API—Create and manage the Network Objects, Service Objects, and collections of these resources in groups 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.ciscosecureaccess.cn/admin/v2
• https://api.ciscosecureaccess.cn/auth/v2
• https://api.ciscosecureaccess.cn/deployments/v2
• https://api.ciscosecureaccess.cn/policies/v2
• https://api.ciscosecureaccess.cn/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.ciscosecureaccess.cn/auth/v2/token

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

Sample Request

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

curl --user '<key>:<secret>' --request POST --url 'https://api.ciscosecureaccess.cn/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.ciscosecureaccess.cn/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

Sample 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.ciscosecureaccess.cn/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 China API collections, see Pagination.
• For information about the Secure Access China API rate limits, see Rate Limits.
• For information about the Secure Access China HTTP response codes, see Errors and Troubleshooting.

OAuth 2.0 Scopes

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

Samples

We provide code examples, Postman collections, and curl samples to help you create your first Secure Access API request. For more information, see the API Reference.

• Cisco Secure Access API Postman Examples