1. Getting Started¶

Users can generate API client credentials, which can be used to access the Cisco SecureX threat response APIs programmatically.

Refer to the Cisco Threat Response API Client Documentation for more info on how to create an API client.

1.1. Global API Endpoint URLs¶

To find the correct API endpoint URL query https://visibility.amp.cisco.com/clouds.json and present the user with the name of the region. Then save it and use the appropriate URLs for the region.

The current available regional API endpoints are:

1.2. Create API Client in Threat Response UI¶

When creating your API client, you will receive a Client ID and Client Password which will be used to retrieve an access token in the next step.

1.3. Scopes¶

There are twelve scopes available when adding a new client. A single scope can be selected or any mix of the scopes can be chosen.

Casebook	Access and modify your casebooks
Enrich	Query your configured modules for threat intelligence (Read Only)
Global Intelligence	Access AMP Global Intelligence (Read Only)
Inspect	Extract observables and data from text (Read Only)
Integration	Manage your modules (Read Only)
Private Intelligence	Access AMP Private Intelligence
Profile	Get your profile information
Registry	Manage registry entries
Response	List and execute response actions using configured modules
SSE	SSE Integration. Manage your Devices (Read Only)
Telemetry	Collect application data for analytics (Write Only)
Ui Settings	Save user settings
Users	Manage users of your organization

The scopes can be selected when creating API Clients at https://visibility.amp.cisco.com/settings/apiClients

Warning

Security access control best practice requires providing a user or service least access. When designing API workflows, it is often desirable to have more than one set of API client credentials for destructive and non destructive API operations. API clients can be created to have different combinations of scopes which can be used to map out and provide least access to different parts of a client application.

1.4. Using API Client Credentials to Get Access Token¶

You cannot access the API directly using the Client ID and Client Password because Threat Response requires the use of an Access Token. You can request a token from the OAuth2 Token Api.

http

POST https://visibility.amp.cisco.com/iroh/oauth2/token HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "client_id": "client-38bbc74d-f7d1-452b-8777-fb8c7d985475",
    "client_password": "FIz1FDf40ms0mNpc9oS8AJQJ2Vyw0aUtE17XWZWEQ71IMs13J8AQFD",
    "grant_type": "client_credentials"
}

Example using Bash with a curl command:

client_id="client-38bbc74d-f7d1-452b-8777-fb8c7d985475"
client_password="FIz1FDf40ms0mNpc9oS8AJQJ2Vyw0aUtE17XWZWEQ71IMs13J8AQFD"
    curl -X POST \
     -u "$client_id:$client_password" \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     -d 'grant_type=client_credentials' \
     'https://visibility.amp.cisco.com/iroh/oauth2/token'

JSON Response:

{
  "access_token":"eyJhbGciO...",
  "token_type":"bearer",
  "expires_in":600,
  "scope":"enrich:read casebook inspect:read"
}

Description of Response:

access_token	Indicates what you pass in the authorization header
token_type	Indicates it should be presented as a certain type of token
expires_in	Indicates how many seconds this token is valid. You will need to request a new one after it expires, using the same API call
scope	Contains a list of scopes that were granted to this token. It may not include all of the scopes for which the client was authorized if your user identity has lost privileges since the API Client was created

Once an Access Token has been created, you can call the APIs you granted the API Client permissions to access. See documentation here.

1.5. Authentication¶

All Threat Response APIs use an Access Token for authentication. This is an opaque value which is passed in as an HTTP header: Authorization: Bearer <Access Token>. Access Tokens are short-lived, and can be requested or refreshed from the OAuth2 Token Api.

For more information please see: https://visibility.amp.cisco.com/help/integration

1.6. Rate Limits¶

To protect our infrastructure, we apply rate limits to API requests. The current limit is 8000 requests per rolling 60 minute window. When you make a request, the X-Ratelimit-Org-Limit header will tell you the rate limit being applied.

Warning

If you go over your rate limit, you will get a 429 Too Many Requests response code. When developing your integration with Cisco SecureX threat response, you should ensure the you are staying under the quota, as well as handling the HTTP 429 error gracefully and throttling your requests.

More information and examples of rate limits can be found at: https://visibility.amp.cisco.com/help/integration

1.7. API Endpoints¶

There are six available APIs used for integrations. These include:

Inspect	Parses a string of text and extracts supported observables
Enrich	Manage users of your organization Used to get query for information about an observable or to pivot to a product UI
Response	Used to take action on an observable within a product
OAuth2	Used to get a token
Global-Intel	Global instance of CTIA only has read access
Private-Intel	Customer specific instance of CTIA where Casebooks, Snapshots, Investigations, etc are stored

More information can be found at: https://visibility.amp.cisco.com/help/integration