First steps toward using the APIs

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

  1. Prepare the development and runtime environment.

    Running the sample code in this guide requires:

    • Network access to Trend 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: requestsand ldap3

        You can install the libraries using the pipcommand.
  2. Obtain an authentication token.

    If you have access to the User Accounts screen of your organization's Trend Vision One console, see Obtain authentication tokens. Otherwise, contact your system administrator.

  3. Test your authentication token by sending requests to the API:
Tip:

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

Obtain authentication tokens

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

  1. On the Trend Vision One console, go to Administration > API Keys.
  2. 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.
  3. 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 Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Built-in roles

Trend 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 Trend Vision One features

Operator (formerly Administrator)

Can configure system settings and connect products

Auditor

Has "View" access to specific Trend 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 Trend Vision One API documentation, visit the Trend 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 Trend Vision One API documentation, visit the Trend Vision One Automation Center.

cURL

Retrieve a list of the available detection models using cURL.

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

  2. 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 Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Python

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

  1. Create a file named first_steps_get_example.py.
  2. 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)
  3. Locate the following line and change the value:
    token = 'YOUR_TOKEN'
  4. Open the command prompt (Windows) or terminal (Linux, macOS) and run the following command:
    python first_steps_get_example.py
Tip:

For the complete Trend Vision One API documentation, visit the Trend 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 Trend Vision One API documentation, visit the Trend Vision One Automation Center.

cURL

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

  1. 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"
  }
]
  2. 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 Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Python

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

  1. Create a file named first_steps_post_example.py.
  2. 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)
  3. Locate the following lines and change the values:

    • {'modelId': 'YOUR_MODELID'}

    • token = 'YOUR_TOKEN'

  4. Open a command prompt (Windows) or terminal (Linux) and run the following command: 
    python first_steps_post_example.py
Tip:

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