Links

PlexTrac API Overview

The PlexTrac API enables customized access to PlexTrac for sending and receiving data. The purpose of this section is to provide an overview of the PlexTrac API and object structure, help prepare and understand what is needed to begin, and provide guidance to complete common use cases.
This section is broken up into the following pages:
  • Getting Started: Explains the usage of Bearer tokens an authentication for all endpoints and an overview of the folder structure within Postman.
  • Object Structures: Provides an explanation of how data for findings and assets are stored in the database, as well as definitions of fields and sample structure files for viewing and downloading.
  • Retrieving Parameter IDs: Provides a list of common parameter IDs and instructions on how to find them within the PlexTrac platform.
  • Common Endpoints List: Provides a list of common use cases to easily scroll through and find the desired folder in Postman that matches the objective.

Getting Started

The PlexTrac API uses Bearer tokens to manage authentication for all API endpoints. Two endpoints are used to authenticate to get a valid Bearer token, depending if the user has multi-factor authorization (MFA) set up or not.
This token is then sent as an Authorization header to all other endpoints. These tokens expire after 15 minutes and will need to be refreshed, or the user will need to re-authenticate.

Authentication

POST Authentication is the basic auth endpoint and returns the following after successfully verifying the given username and password for a user without MFA:
The value in the token field is the required Bearer token sent to other endpoints.
When the user does have MFA enabled, the response will look different. In this scenario, the code field has a value related to the MFA authentication method set up by the user (i.e., Azure, Okta, etc.). This code must be sent with the request payload in the POST Multi-Factor Authentication endpoint. PlexTrac will check the 6-digit code with this code to verify and send the familiar response from the first endpoint with the Bearer token as the value:

Sending Bearer Token with Requests

Once created, the Bearer token is sent as an Authorization Header with any other endpoints. Using the requests module in Python, an example call would be the following:
Using cURL on the command line, a request example would be the following:

Folder Structure on Postman

Postman folder
description
v1/v2
A set of endpoints created for PlexTrac. The first two folders (v1 and v2) are not different versions of the same endpoints but contain different API calls.
Graph QL Queries
GraphQL SELECT queries used to read or fetch values in parallel
Graph QL Mutations
GraphQL INSERT, UPDATE, and DELETE queries used to write or post values in sequence
Click Next below to for an explanation of object structures.