Secure Endpoint API - Authentication

Authentication

The Secure Endpoint API requires access via an authenticated and authorized account. Only authorized accounts are able to submit requests to API operations. All operations must communicate over a secure HTTPS connection.

To authenticate and access the Secure Endpoint API, perform the following:

1. Integrate Secure Endpoint with Cisco XDR or Secure Client Cloud Management.

1. Navigate to the Secure Endpoint console.

2. Click the Integrate Now button on the Secure Endpoint Dashboard.

   This enables the integration between Secure Endpoint and Cisco XDR or Secure Client Cloud Management.

   

3. Navigate to the Cisco XDR or Secure Client Cloud Management console and verify the integration.

4. Enable the Integration (Cisco XDR only)

Navigate to Administration -> Integrations, then click

2. Register the API Client.

From within either Cisco XDR or Secure Client Cloud Management

1. Navigate to Administration -> API Clients.

2. On the API Clients page, click the Generate API Client button to open the Add New Client form.

   

3. Enter a Client Name and select a Scope.

4. Optionally, enter a Description and click Add New Client.

   The Client Id and Client Password are generated and will appear on the Add New Client form.

3. Generate an API Access Token.

Use the following OAuth2 token API to generate an API access token:

The Client-Id and Client-Password (Client-Secret per OAuth2) generated in the previous step are required to call the token endpoint.

Get an Access Token via the Token API:

# Read in the client_id and client_secret if they are not already set.
[ -z "$client_id" ] && read -p "client_id: " client_id
[ -z "$client_secret" ] && read -p "client_secret: " client_secret

# Call the token endpoint and store the result in a variable.
result=$(curl -s 'https://visibility.amp.cisco.com/iroh/oauth2/token' \
     --user "${client_id}:${client_secret}" \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     -d 'grant_type=client_credentials')

# Extract the access_token from the result.
export BEARER_TOKEN=$(echo "$result" | jq -r .access_token)

# Print the result.
[ -x "$(command -v jq)" ] && echo "$result" | jq . || echo "$result"

Response:

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

4. Generate Secure Endpoint API Access Token.

Use the following access token endpoint to generate a Secure Endpoint API access token:

The API access token generated in previous step is required to call the token endpoint.

Get and Access Token from the Secure Endpoint Token API:

# Call the Secure Endpoint token endpoint and store the result in a variable.
result=$(curl -s 'https://api.amp.cisco.com/v3/access_tokens' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $BEARER_TOKEN" \
     -d 'grant_type=client_credentials')

# Extract the access_token from the result.
export BEARER_TOKEN=$(echo "$result" | jq -r .access_token)

# Print the result.
[ -x "$(command -v jq)" ] && echo "$result" | jq . || echo "$result"

Response:

{
  "access_token": "eyJhbGciO..."
}

5. Access Secure Endpoint API.

The token generated in previous step is used to access the Secure Endpoint APIs.

Request:

# Call the Secure Endpoint API and store the result in a variable.
result=$(curl -s 'https://api.amp.cisco.com/v3/organizations?size=10' \
                --header "Authorization: Bearer ${BEARER_TOKEN}")

# Print the result.
[ -x "$(command -v jq)" ] && echo "$result" | jq . || echo "$result"

Response:

{
  "meta": {
    "start": 0,
    "size": 10,
    "total": 2
  },
  "data": [
    {
      "name": "Example Organization #1",
      "organizationIdentifier": "4baascfeaofqpxidpinxtt5l"
    },
    {
      "name": "Example Organization #2",
      "organizationIdentifier": "nxtf3phj4w0z41pim3vqarzk"
    }
  ]
}

A script of this example is available as examples.sh.