Authentication

In order to access the Cisco XDR APIs programmatically, users must get an access token. There are two ways to get an access token:

  • Using API Client credentials
  • Using OAuth Code Client credentials

Get Access Token

Using API Client Credentials To Get Access Token

If you do not already have API Client credentials, please follow the steps in the API Clients guide in order to configure an API client and obtain credentials.

You cannot access the Cisco XDR APIs directly using the Client ID and Client Password from the API Client credentials. You must generate an Access Token using the API Client credentials.

Use the OAuth2 token API to generate an access token.

Example using Bash with a cURL command:

client_id="[clientid]"
client_password="[client-password]"
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'

Response:

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

Description of Response:

  • The access_token value is what you pass in the authorization header.
  • The token_type value indicates it should be presented as a bearer token.
  • The 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 request.
  • The scope value 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. For an overview of all of the scopes, please see the Authorization Access section.

Once you have an the access_token, you can make API requests for APIs that were granted access in the API Client creation.

Using OAuth Code Client Credentials To Get Access Token

For instructions about how to retrieve the access token from an OAuth Code Client, see the Integration Developer Documentation.

Access Token Expiration and Refresh

Access tokens are short-lived and expires based on the value indicated in the expires_in field of the token request response (see above). When a token expires, a new one can be requested or refreshed with the OAuth2 token API.

API Authentication

All Cisco XDR APIs use an access token for authentication. This is an opaque value which is passed in as an HTTP header: Authorization: Bearer <Access Token>.

Example request using cURL:

ACCESS_TOKEN="eyJhbGciO..."
curl -X POST \
     --header "Authorization: Bearer $ACCESS_TOKEN" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     -d '{"content":"cisco.com"}' \
     'https://visibility.amp.cisco.com/iroh/iroh-inspect/inspect'
[{"value":"cisco.com","type":"domain"}]