Authentication
The Umbrella API provides a standard REST interface and supports the OAuth 2.0 client credentials flow. To get started, log in to Umbrella and create an Umbrella API key. Then, use your API credentials to generate an API access token.
Note: API keys, passwords, secrets, and tokens allow access to your private customer data. Never share your credentials with another user or organization.
Prerequisites
- You must have an Umbrella user account with the Full Admin role.
Log in to Umbrella
Log in to Umbrella with the following URL:
https://dashboard.umbrella.com
You can find your username after Admin in the navigation tree. Confirm that your organization appears under your username.
API Key Use Cases
You can create various types of API key. The Umbrella Key Admin API enables you to provision and manage Umbrella API keys. Use your Umbrella API keys or legacy Umbrella API keys to create and manage network entities and users, access your reports, manage policies, and integrate your systems and devices with the Cisco Cloud Security platform.
Key Type | Description | Use Cases |
---|---|---|
Umbrella API key | Secure, intent-based API key with configured scopes and expiration date. | View and manage your deployments, users, and policies. View reports and logs. |
Legacy Umbrella API key | API key that supports access to multiple API resources using Basic authentication. For more information, see Authentication. | View and manage your deployments, users, and policies. View reports and logs. |
Umbrella Key Admin API key | Secure API key with configured permissions and expiration date. | View and manage the Umbrella API keys in your organization. |
Manage API Keys
Create and manage Umbrella API keys.
Create Umbrella API Key
Create an Umbrella API key ID and key secret.
Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.
Click API Keys and then click Add.
- The number of expired API keys appears next to the red triangle.
- The number of API keys that expire within 30 days appears next to the yellow triangle.
Enter a name and description for the key. A name must contain fewer than 256 characters. The description is optional.
Check the key scopes and expand a key scope to view the scope categories. Check each scope category in a key scope to enable access to the API endpoints. For information about the Umbrella API key scopes, see OAuth 2.0 Scopes.
Choose Read-Only or Read / Write for the selected scope and resource.
For Expiry Date, choose the expiration date for the key, or choose Never expire.
(Optional) For Network Restrictions, enter a comma-separated list of public IP addresses or CIDRs, then click ADD.
Note: You can add up to ten networks to your API key. You can only use your API key to authenticate requests for clients on the selected networks.
Click Create Key.
Copy and save your API Key and Key Secret.
Click Accept And Close.
Refresh Umbrella API Key
Refresh an Umbrella API key ID and key secret.
Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console, navigate to Console Settings > API Keys.
Click API Keys, and then expand an API key.
Click Refresh Key.
Copy and save your API Key and Key Secret.
Click Accept and Close.
Update Umbrella API Key
Update an Umbrella API key.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console, navigate to Console Settings > API Keys.
Click API Keys, and then expand an API key. You can modify the API Key Name, Description, selected scopes and permissions in Key Scope, and Expiry Date.
For Network Restrictions, update the list of IP addresses and CIDRs. Click on the X to remove a network address.
Click Save.
Delete Umbrella API Key
Delete an Umbrella API key.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console, navigate to Console Settings > API Keys.
Click API Keys, and then expand an API key.
Click Delete. In the dialog window, click Delete to remove the API key from your organization.
Manage Key Admin API Keys
Create and manage Umbrella Key Admin API keys.
Create Key Admin Key
Create a Key Admin API key and secret.
Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.
Click KeyAdmin Keys, and then click Add.
- The number of expired API keys appears next to the red triangle.
- The number of API keys that expire within 30 days appears next to the yellow triangle.
Enter a name and description for the key. A name must contain fewer than 256 characters. The description is optional.
Check the permissions for the key.
For Expiry Date, choose the expiration date for the key, or choose Never expire.
(Optional) For Network Restrictions, enter a comma-separated list of public IP addresses or CIDRs, then click ADD.
Note: You can add up to ten networks to your API key. You can only use your API key to authenticate requests for clients on the selected networks.
Click Create Key.
Copy and save your KeyAdmin Key and Key Secret.
Click Accept And Close.
Refresh Key Admin Key
Refresh a Key Admin API key and secret.
Note: You have only one opportunity to copy your API secret. Umbrella does not save your API secret and you cannot retrieve the secret after its initial creation.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.
Click KeyAdmin Keys, and then expand an API key.
Click Refresh Key.
Copy and save your KeyAdmin Key and Key Secret.
Click Accept and Close.
Update Key Admin Key
Update a Key Admin API key.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.
Click KeyAdmin Keys, and then expand an API key. You can modify the Key Admin Key Name, Description, Permissions, Expiry Date, and Network Restrictions.
Click Save.
Delete Key Admin Key
Delete a Key Admin API key.
Navigate to Admin > API Keys or in a Multi-org, Managed Service Provider (MSP), or Managed Secure Service Provider (MSSP) console navigate to Console Settings > API Keys.
Click KeyAdmin Keys, and then expand an API key.
Click Delete. In the dialog window, click Delete to remove the API key from your organization.
Generate an API Access Token
The Umbrella Token Authorization API authenticates your API credentials. This service creates a Bearer token. You can include your short-lived token in the Authorization
header of each Umbrella API operation.
Note: You can use any standards-based OAuth 2.0 client library to create an API token.
Umbrella Token Authorization API endpoint:
POST https://api.umbrella.com/auth/v2/token
Best Practices
The Umbrella 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 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.
Troubleshooting
For information about error conditions that may occur when you generate an access token or authorize an Umbrella API request, see Errors and Troubleshooting.
Token Authorization Request
Use the Umbrella API credentials that you created for your organization to generate an API access token.
Request
In the curl
sample, substitute your Umbrella API key and secret for the value of the user
option.
curl --user '<key>:<secret>' --request POST --url 'https://api.umbrella.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.umbrella.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
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 before the token expires. |
Response
Sample response (200
, OK):
{
"token_type": "bearer",
"access_token": "xxxxxx",
"expires_in": 3600
}
Token Authorization Request for Multi-Org and Managed Child Organizations
Create your Umbrella API credentials (parent org) on the Multi-org or provider console. Then, use these credentials to generate an API access token for the parent (provider) organization or the child (customer) organization of the provider.
API Endpoints Available For Parent and Child Organizations
These API endpoints only accept a parent (provider) organization access token. You can specify the child organization ID in the X-Umbrella-OrgId
request header to generate the access token for a specific child (customer) organization of the provider.
- GET
/admin/v2/config/contacts
- POST
/admin/v2/config/contacts
- GET
/admin/v2/config/contacts/{contactId}
- PUT
/admin/v2/config/contacts/{contactId}
- DELETE
/admin/v2/config/contacts/{contactId}
- GET
/admin/v2/config/logos
- POST
/admin/v2/config/logos
- GET
/admin/v2/config/logos/{logoId}
- PUT
/admin/v2/config/logos/{logoId}
- DELETE
/admin/v2/config/logos/{logoId}
API Endpoints Available Only For Parent Organizations
The following API endpoints only accept an access token generated with a parent (provider) organization's API credentials. Set a child organization ID for the customerId
path parameter.
- GET
/admin/v2/config/cnames
- POST
/admin/v2/config/cnames
- GET
/admin/v2/config/cnames/{cnameId}
- PUT
/admin/v2/config/cnames/{cnameId}
- DELETE
/admin/v2/config/cnames/{cnameId}
- POST
/admin/v2/providers/customers/{customerId}/trialExtensions
- POST
/admin/v2/providers/customers/{customerId}/accessRequests
- GET
/admin/v2/providers/customers/{customerId}/accessRequests/{accessRequestId}
- PUT
/admin/v2/providers/customers/{customerId}/accessRequests/{accessRequestId}
- GET
/admin/v2/providers/customers/{customerId}/trialStrengths
- GET
/admin/v2/providers/customers/{customerId}/subscriptionDetails
- GET
/admin/v2/providers/customerAddresses
- GET
/admin/v2/providers/customers/packages
- GET
/admin/v2/providers/customerDeals/{dealId}
- PUT
/admin/v2/providers/customerDeals/{dealId}
- GET
/reports/v2/providers/customers/downloadReportRequests
- GET
/reports/v2/providers/category-requests-by-org
- GET
/reports/v2/requests-by-category
- GET
/admin/v2/organizations
- POST
/admin/v2/passwordresets/{customerId}
Request
In the curl
sample:
- Substitute your Umbrella API key and secret for the value of the
user
option. - Set the
X-Umbrella-OrgId
request header with the child organization ID.
curl --user '<key>:<secret>' --request POST --url 'https://api.umbrella.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-Umbrella-OrgId: <child organizationId>' \
-d 'grant_type=client_credentials'
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 before the token expires. |
Response
Sample response (200
, OK):
{
"token_type": "bearer",
"access_token": "xxxxxx",
"expires_in": 3600
}
Token Authorization Request for Partner Proof of Value Parent Organizations
Use the Umbrella API credentials that you created for your Partner Proof of Value (PPoV) parent organization to generate an API access token for child organizations of PPoV parent organizations.
API Endpoints Available Only For Partner Proof of Value Parent Organizations
The following API endpoints accept Partner Proof of Value (PPoV) parent organization tokens. Set a child organization ID for the customerId
path parameter.
- POST
/reports/v2/providers/customers/{customerId}/securityReportRequests
Request
In the curl
sample:
- Substitute your Umbrella API key and secret for the value of the
user
option. - Set the
X-Umbrella-OrgId
request header with the child organization ID.
curl --user '<key>:<secret>' --request POST --url 'https://api.umbrella.com/auth/v2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-Umbrella-OrgId: <child organizationId>' \
-d 'grant_type=client_credentials'
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 before the token expires. |
Response
Sample response (200
, OK):
{
"token_type": "bearer",
"access_token": "xxxxxx",
"expires_in": 3600
}