# CISCO Secure Endpoint - Secure Endpoint API

#### <span style="color: rgb(53, 152, 219);">**Authentication** </span>

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.**

- Navigate to the Secure Endpoint console.
- 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.

Integrate xdr :

- Navigate to the Cisco XDR or Secure Client Cloud Management console and verify the integration.
- Enable the Integration (Cisco XDR only)
- Navigate to Administration -&gt; Integrations, then click + Enable
- Enable Secure Endpoint

**2. Register the API Client.**

- From within either Cisco XDR or Secure Client Cloud Management
- Navigate to Administration -&gt; API Clients.
- On the API Clients page, click the Generate API Client button to open the Add New Client form. 
    - add new client form
- Enter a Client Name and select a Scope. 
    - Note: The Secure Endpoint API will work with any of the selected Scopes.
    - The API Client will have the same permissions within Secure Endpoint as the creator of the API Client.
- 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. api credential form
- Secure the Client ID and Client Password before closing the window. Copy and paste it properly.

**3. Generate an API Access Token.**

#### <span style="color: rgb(53, 152, 219);">**Method 1: Linux** </span>

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

<table border="1" id="bkmrk-north-america-https%3A" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 49.881%;"></col><col style="width: 49.881%;"></col></colgroup><tbody><tr><td>North America</td><td>[https://visibility.amp.cisco.com/iroh/oauth2/token](https://visibility.amp.cisco.com/iroh/oauth2/token)</td></tr><tr><td>Asia Pacific, Japan, and China</td><td>[https://visibility.apjc.amp.cisco.com/iroh/oauth2/token](https://visibility.apjc.amp.cisco.com/iroh/oauth2/token)</td></tr><tr><td>Europe</td><td>[https://visibility.eu.amp.cisco.com/iroh/oauth2/token](https://visibility.eu.amp.cisco.com/iroh/oauth2/token)</td></tr></tbody></table>

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:

<table border="1" id="bkmrk-%23-read-in-the-client" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>\# Read in the client\_id and client\_secret if they are not already set.   
\[ -z "$client\_id" \] &amp;&amp; read -p "client\_id: " client\_id   
\[ -z "$client\_secret" \] &amp;&amp; read -p "client\_secret: " client\_secret   
   
\# Call the token endpoint and store the result in a variable.   
result=$(curl -s 'https://visibility.eu.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)" \] &amp;&amp; echo "$result" | jq . || echo "$result" </td></tr></tbody></table>

Response:

<table border="1" id="bkmrk-%7B%C2%A0%C2%A0-%22access_token%22%3A-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>{   
 "access\_token": "eyJhbGciO...",   
 "token\_type": "bearer",   
 "expires\_in": 600,   
 "scope": "enrich:read casebook inspect:read"   
} </td></tr></tbody></table>

4\. Generate Secure Endpoint API Access Token.

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

<table border="1" id="bkmrk-north-america-https%3A-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 49.881%;"></col><col style="width: 49.881%;"></col></colgroup><tbody><tr><td>North America</td><td>[https://api.amp.cisco.com/v3/access\_tokens ](https://visibility.amp.cisco.com/iroh/oauth2/token)</td></tr><tr><td>Asia Pacific, Japan, and China</td><td>[https://api.apjc.amp.cisco.com/v3/access\_tokens ](https://visibility.apjc.amp.cisco.com/iroh/oauth2/token)</td></tr><tr><td>Europe</td><td>[https://api.eu.amp.cisco.com/v3/access\_tokens ](https://visibility.eu.amp.cisco.com/iroh/oauth2/token)</td></tr></tbody></table>

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:

<table border="1" id="bkmrk-%23-call-the-secure-en" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>\# 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)" \] &amp;&amp; echo "$result" | jq . || echo "$result" </td></tr></tbody></table>

  
Response:

<table border="1" id="bkmrk-%7B%C2%A0%C2%A0-%22access_token%22%3A--1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>{   
 "access\_token": "eyJhbGciO..."   
}   
 </td></tr></tbody></table>

5\. Access Secure Endpoint API.

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

Request:

<table border="1" id="bkmrk-%23-call-the-secure-en-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>\# 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)" \] &amp;&amp; echo "$result" | jq . || echo "$result"

</td></tr></tbody></table>

   
 Response:

<table border="1" id="bkmrk-%7B%C2%A0%C2%A0-%22meta%22%3A-%7B%C2%A0%C2%A0-%C2%A0-%22s" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>{   
 "meta": {   
 "start": 0,   
 "size": 10,   
 "total": 2   
 },   
 "data": \[   
 {   
 "name": "Example Organization #1",   
 "organizationIdentifier": "4baascfeaofqpxidpinxtt5l"   
 },   
 {   
 "name": "Example Organization #2",   
 "organizationIdentifier": "nxtf3phj4w0z41pim3vqarzk"   
 }   
 \]   
} </td></tr></tbody></table>

#### <span style="color: rgb(53, 152, 219);">**Method 2: Windows** </span>

1\. Set Client ID and Client Secret

The script reads client\_id and client\_secret from the user if not set and uses them to request an OAuth2 token.

<table border="1" id="bkmrk-%40echo-off%C2%A0rem-check-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>@echo off   
REM Check if client\_id and client\_secret are set   
if "%client\_id%"=="" set /p client\_id="Enter client\_id: "   
if "%client\_secret%"=="" set /p client\_secret="Enter client\_secret: "   
   
REM Call the OAuth2 token endpoint   
curl -s -u "%client\_id%:%client\_secret%" ^   
 -H "Content-Type: application/x-www-form-urlencoded" ^   
 -H "Accept: application/json" ^   
 -d "grant\_type=client\_credentials" ^   
 https://visibility.amp.cisco.com/iroh/oauth2/token &gt; token.json   
   
REM Extract the access\_token using jq (ensure jq is installed)   
for /f "delims=" %%A in ('jq -r ".access\_token" token.json') do set BEARER\_TOKEN=%%A   
   
REM Output the token   
echo OAuth2 Access Token: %BEARER\_TOKEN% </td></tr></tbody></table>

  
2\. Generate Secure Endpoint API Access Token

Use the token from the previous step to generate an API access token for Secure Endpoint.

<table border="1" id="bkmrk-%40echo-off%C2%A0rem-call-t" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>@echo off   
REM Call the Secure Endpoint token endpoint   
curl -s -X POST ^   
 -H "Content-Type: application/x-www-form-urlencoded" ^   
 -H "Accept: application/json" ^   
 -H "Authorization: Bearer %BEARER\_TOKEN%" ^   
 -d "grant\_type=client\_credentials" ^   
 https://api.amp.cisco.com/v3/access\_tokens &gt; endpoint\_token.json   
   
REM Extract the access\_token using jq (ensure jq is installed)   
for /f "delims=" %%A in ('jq -r ".access\_token" endpoint\_token.json') do set SECURE\_ENDPOINT\_TOKEN=%%A   
   
REM Output the Secure Endpoint API token   
echo Secure Endpoint API Access Token: %SECURE\_ENDPOINT\_TOKEN% </td></tr></tbody></table>

  
3\. Access the Secure Endpoint API

<table border="1" id="bkmrk-%40echo-off%C2%A0rem-call-t-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 99.881%;"></col></colgroup><tbody><tr><td>@echo off   
REM Call the Secure Endpoint API   
curl -s -X GET ^   
 -H "Authorization: Bearer %SECURE\_ENDPOINT\_TOKEN%" ^   
 https://api.amp.cisco.com/v3/organizations?size=10 &gt; organizations.json   
   
REM Output the API response   
echo Secure Endpoint API Response:   
type organizations.json </td></tr></tbody></table>

  
 Key Notes:

Prerequisites:

- Install curl (default on Windows 10/11 or available via Chocolatey).
- Install jq for JSON parsing (available via jq).
- Save and Run:
- Save the script as a .bat file (e.g., get\_token.bat).
- Run the script in Command Prompt or PowerShell.
- Replace Region URLs:
- Use the appropriate region URL in the curl commands (e.g., North America, APJC, or Europe).

Source: https://developer.cisco.com/docs/secure-endpoint/authentication/#3-generate-an-api-access-token