First steps toward using the APIs

Become familiar with the APIs by sending sample requests to TrendAI Vision One™.

Prepare the development and runtime environment.

Running the sample code in this guide requires:

Network access to TrendAI Vision One™.

A tool for sending requests.


Type	Requirements
cURL command	HTTP client such as Postman, Paw, or cURL
Python script	Python 3.7.x or later Additional libraries: `requests`and `ldap3` You can install the libraries using the `pip`command.

Obtain an authentication token.

If you have access to the User Accounts screen of your organization's TrendAI Vision One™ console, see Obtain authentication tokens. Otherwise, contact your system administrator.
Test your authentication token by sending requests to the API:
- Send GET requests
- Send POST requests

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Obtain authentication tokens

Generate authentication tokens in the TrendAI Vision One™ console to access the APIs.

On the TrendAI Vision One™ console, go to Administration > API Keys.
Generate a new authentication token.
1. Click Add API key.
2. Specify the settings of the new API key.
  Tip:
  
  Use the principle of least privilege when configuring API keys.
  - Name: A meaningful name that can help you identify the API key (Example: MS_Sentinel_API_Token).
  - Role: The user role assigned to the key. API keys can use either predefined or custom user roles.
  - Expiration time: The time the API key remains valid.
    
    By default, authentication tokens expire one year after creation. However, a master administrator can delete and re-generate tokens at any time.
  - Status: Whether the API key is enabled.
  - Details: Extra information about the API key.
3. Click Add.
Copy and store the authentication token in a secure location.

Important:

You cannot see the authentication token again after you click Close.

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Built-in roles

TrendAI Vision One™ has built-in roles with fixed permissions that Master Administrators can assign to accounts.

The following table provides a brief description of each role.


Role	Description
Master Administrator	Can access all apps and TrendAI Vision One™ features
Operator (formerly Administrator)	Can configure system settings and connect products
Auditor	Has "View" access to specific TrendAI Vision One™ apps and features
Senior Analyst	Can investigate XDR alerts, take response actions, approve Managed XDR requests, and manage detection models
Analyst	Can investigate XDR alerts and take response actions

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Send GET requests

Learn how to send GET requests to the List detection models API.

For more information, see the Detection Models section of the API reference.

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

cURL

Retrieve a list of the available detection models using cURL.

Use the following information to create the request.
- Request type: GET
- URL: https://api.usgov.xdr.trendmicro.com/v3.0/threatintel/suspiciousObjectExceptions
- Header:
  - Key: Authorization
  - Value: Bearer <your authentication token>

Open the command prompt (Windows) or terminal (Linux, macOS) and execute the following command:

curl -X GET https://api.usgov.xdr.trendmicro.com/v3.0/threatintel/suspiciousObjectExceptions \
-H "Authorization: Bearer <your authentication token>

Tip:

You can also use other HTTP clients such as Paw or Postman.

The API returns the following response body:

{
  "items": [
    {
      "domain": "v1.test.com",
      "type": "domain",
      "description": "sample exception data",
      "lastModifiedDateTime": "2021-05-31T00:28:30Z"
    },
    ...
  ]
}

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Python

Retrieve a list of the available detection models using a Python script.

Create a file named first_steps_get_example.py.

Copy and paste the following code into the file.

import requests
import json

url_base = 'https://api.usgov.xdr.trendmicro.com'
url_path = '/v3.0/threatintel/suspiciousObjectExceptions'
token = 'YOUR_TOKEN'

query_params = {}
headers = {
    'Authorization': 'Bearer ' + token
}

r = requests.get(url_base + url_path, params=query_params, headers=headers)

print(r.status_code)
for k, v in r.headers.items():
    print(f'{k}: {v}')
print('')
if 'application/json' in r.headers.get('Content-Type', '') and len(r.content):
    print(json.dumps(r.json(), indent=4))
else:
    print(r.text)

Locate the following line and change the value:
token = 'YOUR_TOKEN'
Open the command prompt (Windows) or terminal (Linux, macOS) and run the following command:
python first_steps_get_example.py

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Send POST requests

Learn how to send POST requests to the Enable or disable a detection model API.

For more information, see the Detection Models section of the API reference.

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

cURL

Enable or disable detection models based on your organization's security requirements using cURL.

Use the following information to create the request.
- Request type: POST
- URL: https://api.usgov.xdr.trendmicro.com/v3.0/threatintel/suspiciousObjectExceptions
- First header:
  - Key: Authorization
  - Value: Bearer <your authentication token>
- Second header:
  - Key: Content-Type
  - Value: application/json
- Request body:
```
[
  {
    "domain": "v1g.test.com"
  }
]
```

Open the command prompt (Windows) or terminal (Linux, macOS) and execute the following command:

curl -X POST https://api.usgov.xdr.trendmicro.com/v3.0/threatintel/suspiciousObjectExceptions \
-H "Authorization: Bearer <your authentication token>" \
-H "Content-Type: application/json" \
-d '[
  {
    "domain": "v1g.test.com"
  }
]'

Tip:

You can also use other HTTP clients such as Paw or Postman.

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Python

Enable or disable detection models based on your organization's security requirements using a Python script.

Create a file named first_steps_post_example.py.

Copy and paste the following code into the file.

import requests
import json

url_base = 'https://api.usgov.xdr.trendmicro.com'
url_path = '/v3.0/threatintel/suspiciousObjectExceptions'
token = 'YOUR_TOKEN'

query_params = {}
headers = {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json;charset=utf-8'
}
body = [
    {
        'domain': 'v1g.test.com',
    }
]

r = requests.post(url_base + url_path, params=query_params, headers=headers, json=body)

print(r.status_code)
for k, v in r.headers.items():
    print(f'{k}: {v}')
print('')
if 'application/json' in r.headers.get('Content-Type', '') and len(r.content):
    print(json.dumps(r.json(), indent=4))
else:
    print(r.text)

Locate the following lines and change the values:
- {'modelId': 'YOUR_MODELID'}
- token = 'YOUR_TOKEN'
Open a command prompt (Windows) or terminal (Linux) and run the following command:
```
python first_steps_post_example.py
```

Tip:

For the complete TrendAI Vision One™ API documentation, visit the TrendAI Vision One™ Automation Center.

Trend Vision One APIs

First steps toward using the APIs

Obtain authentication tokens

Built-in roles

Send GET requests

cURL

Python

Send POST requests

cURL

Python