Cisco Umbrella for Government APIs, Getting Started

Getting Started

The Umbrella for Government API provides a RESTful interface that is described by version 3.x of the OpenAPI specification. The Umbrella for Government API endpoints use JSON for all requests and responses.

Umbrella for Government API Resources

• Key Admin API—Create and manage Umbrella API keys.
• Users and Roles API—Get the organization's user accounts and user roles.
• Roaming Computers API—Get and manage the roaming computers in the organization.
• Networks API—Create, get, and manage the networks and network deployment policies in the organization.
• 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.
• Internal Networks API—Create, get, and manage the internal networks and internal network deployment policies in the organization.
• Internal Domains API—Create, get, and manage the internal domains in the organization.
• Sites API—Create, get, and manage the Umbrella sites in the organization.
• Virtual Appliances API—Get and manage the Umbrella virtual appliances in the organization.
• Network Devices API—Create, get, and manage the network devices in the organization.
• Policies API—Get and manage the policies about the organization's deployments.
• Destination Lists API—Create, get, and manage destination lists and destinations.
• Reporting API—Get various Umbrella 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.
• API Usage Reports API—Get the reports for the organization's API usage.

Base URI

The Umbrella for Government API endpoints begin with the api.umbrellagov.com base URI.

The API endpoints are found within the following API path scopes:

• https://api.umbrellagov.com/admin/v2
• https://api.umbrellagov.com/auth/v2
• https://api.umbrellagov.com/deployments/v2
• https://api.umbrellagov.com/policies/v2
• https://api.umbrellagov.com/reports/v2

Authorization

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

For information about creating your Umbrella API credentials, see Authentication.

Best Practices

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

Note: An Umbrella 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

Umbrella for Government Token Authorization API endpoint:

POST https://api.umbrellagov.com/auth/v2/token

Note: You can use any standards-based OAuth 2.0 client library to create an API access token.

Request

Run the curl or Python sample, providing your Umbrella for Government API key and secret.

curl --user '<key>:<secret>' --request POST --url 'https://api.umbrellagov.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.umbrellagov.com/auth/v2/token'

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

class UmbrellaAPI:
    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 = UmbrellaAPI(token_url, client_id, client_secret)
print("Token: " + str(api.GetToken()))

Response Schema

Response

Sample response (200, OK):

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

Sample API Request

To make an Umbrella for Government API request, substitute your generated Bearer token in the HTTP Authorization header.

For example:

curl -L --location-trusted --request GET --url 'https://api.umbrellagov.com/admin/v2/users' \
-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 operation, Umbrella responds with an HTTP 400 Bad Request or Invalid Request error.

For example:

{ "error": "invalid_request" }

To resolve the error condition, generate a new access token through the Umbrella Token Authorization API.

Troubleshooting

For information about error conditions that may occur generating an access token or authorizing an API request, see Errors and Troubleshooting.

Pagination, Rate Limits, and Response Codes

• For information about how to paginate the Umbrella for Government API collections, see Pagination.
• For information about rate limits that apply to certain Umbrella for Government API endpoints, see Rate Limits.
• For information about HTTP response codes, see Errors and Troubleshooting.

OAuth 2.0 Scopes

• Learn about the Umbrella for Government API OAuth 2.0 scopes. For more information, see OAuth 2.0 Scopes.

Samples

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

• Umbrella Code Samples
• Umbrella Postman Examples