LogoLogo
API DocumentationIntegrationsPlexTrac.com
  • Product Documentation
    • Using This Site
    • Security Advisories
    • Deployment and Maintenance Policy
    • Supported Applications
  • PlexTrac Modules
    • Dashboard
    • Clients
      • Clients Components
      • Creating a Client
      • Managing Clients
      • Managing Client Users
      • Adding Assets to a Client
      • Managing Assets
    • Schedule
      • Schedule Components
      • Creating an Engagement
      • Requesting an Engagement
      • Managing Engagements
      • Engagement Status
    • Assessments
      • Assessment Components
      • Managing Questionnaires
      • Starting an Assessment
      • Taking an Assessment
      • Reviewing an Assessment
      • Submitting an Assessment
    • Reports
      • Report Components
      • Creating a Report
      • Adding from NarrativesDB
      • Editing a Report
      • Using Short Codes in Reports
      • Findings
        • Creating a Finding
        • Collaborative Editing
        • Importing Findings from a File
        • CSV Findings Templates
          • Using Report Findings CSV Template
        • Importing Findings via an Integration
        • Importing Findings from WriteupsDB
        • Finding Status
        • Creating Jira Tickets
        • CVSS Scoring
        • Affected Assets
      • Importing a Report
      • Exporting a Report
    • Priorities
      • Priorities Components
      • Creating a Priority
      • Linking Findings and Assets
      • Managing Priorities
      • Priorities Metrics
    • Content Library
      • Types of Repositories
      • NarrativesDB
        • NarrativesDB Home Page
        • Managing Repositories
        • Managing Users
        • Creating a Repository
        • Managing Sections
        • Creating a Section
      • WriteupsDB
        • WriteupsDB Home Page
        • Managing Repositories
        • Managing Users
        • Creating a Repository
        • Creating a Writeup
        • Copying a Writeup
        • Adding to a Report
        • Importing via CSV Template
      • RunbooksDB
        • RunbooksDB Home Page
        • Managing Repositories
        • Managing Users
        • Creating a Repository
        • Creating a Procedure
        • Creating a Technique
        • Creating a Tactic
        • Creating a Methodology
    • Analytics
      • Findings
      • Assets
      • Runbooks
      • Trends & SLAs
    • Runbooks
      • Managing Engagements
        • Starting an Engagement
        • Submitting an Engagement
      • Managing Test Plans
        • Creating a Test Plan
        • Exporting a Test Plan
  • Tenant Management
    • Account Management
      • Profile (Personal Settings)
        • Managing User Profile
        • Managing Password
        • Setting Up Two-Factor Authentication
      • Account Admin
        • Tenant Settings
          • Account Information
          • General Settings
          • Email Settings
          • Tags Settings
          • Service-Level Agreements (SLAs)
          • Short Codes
        • Customizations
          • Layouts
          • Templates
            • Report Templates
            • Export Templates
            • Style Guides
          • Theme
        • Automations
          • Risk Scoring
            • Creating Equations
            • Managing Priority Equations
          • Parser Actions
        • Integrations & Webhooks
          • Integrations (API)
            • Cobalt
            • Edgescan
            • HackerOne
            • Jira
            • ServiceNow
            • Tenable Vulnerability Management
            • Tenable Security Center
          • Webhooks
        • Security & User Management
          • Audit Log
          • Security
            • Authentication Methods
              • OAuth/OpenID Setup
                • Microsoft Entra ID
                • Google OAuth
                • Okta
                • OpenID Connect
              • SAML Setup
            • General Authentication Settings
            • Authorization
            • Role Based Access (RBAC)
              • Custom Roles
            • Classification Tiers
          • Users
            • Adding Users
            • Managing Users
        • Licensing
          • Licensing
          • Priorities
          • Plex AI
            • Using AI
        • White Labeling
      • Help Center
      • Logout
    • Integrations and File Imports
      • Acunetix
      • BlindSPOT
      • Burp Suite
      • Checkmarx
      • Core Impact
      • HCL AppScan
      • Invicti
      • Nessus
      • Nexpose
      • Nipper
      • Nmap (Assets)
      • Nmap Vulners NSE
      • Nodeware
      • NodeZero
      • OpenVAS
      • OWASP ZAP
      • Pentera
      • Qualys (VM Parser)
      • Qualys (Web App Scanner)
      • RapidFire
      • Scythe
      • Veracode
  • API Documentation
    • Overview
    • Concept Definitions
    • Getting Started
    • Retrieving Parameter IDs
    • Object Structures
      • Client Object
      • Report Object
      • Finding Object
      • Asset Object
      • Evidence Object
    • Use Cases
    • API Change Policy
      • API Change Log
    • Webhooks
      • Webhook Payload Structure
      • Verifying Sender Requests
Powered by GitBook

Resources

  • Privacy Policy
  • Terms of Use
  • Vulnerability Policy

© 2025 PlexTrac, Inc. All rights reserved.

On this page
  • Authentication
  • Expiration and Limits
  • Generate Access Token
  • Generate Access Token (MFA)
  • Sending the Authorization Header with Requests
  • Refreshing Access Token
  • Sending a JSON Payload

Was this helpful?

Export as PDF
  1. API Documentation

Getting Started

PreviousConcept DefinitionsNextRetrieving Parameter IDs

Last updated 2 months ago

Was this helpful?

Authentication

PlexTrac uses JWT tokens to manage authentication for all API endpoints. This token is sent as an authorization header to all endpoints and validates the user has permission to access the requested action.

Upon successful authentication, these tokens are granted to users in a PlexTrac instance and contain the user's permissions. This means the user will have the same permissions regardless of whether they interact with the PlexTrac platform or manually request an API.

Expiration and Limits

After 15 minutes, JWT tokens expire, requiring users to refresh or re-authenticate for a new valid token.

Ten authentication requests are allowed per minute, regardless of the user or whether the attempt was successful. Any additional attempts will result in an error. This limit is enforced to prevent brute-force attacks against the platform. It may be reached naturally if multiple users attempt to sign in simultaneously or if an API script tries to be used concurrently.

Generate Access Token

The value of the token field is the JWT token to be sent to all other endpoints in the Authorization header.

Generate Access Token (MFA)

This method generates a JWT token ONLY when the user's Authentication Provider is set to PlexTrac, and the user DOES have MFA enabled.

{
    "code": "<code value from previous request>",
    "token": "<6-digit authenticator code>"
}

This will return the following after successfully verifying the given MFA data for a user:

The value of the token field is the JWT token to be sent in the Authorization header to all other endpoints.

Sending the Authorization Header with Requests

Once generated, the JWT token is sent as an Authorization Header with all other endpoints. Using the requests module in Python, an example call would be the following:

To make a request using cURL from the command line, consider the following syntax:

Refreshing Access Token

Refreshing a token uses an existing token but must be done before the session expires while the original token is still valid.

Generating a new session token requires your username/password and, if MFA is set up for the user, an MFA code.

The advantage of refreshing is that the user does not need the username/password and MFA code to extend the session. However, refreshing is necessary for users with MFA setup; otherwise, a new MFA code must be entered to generate a new session.

Sending a JSON Payload

Some endpoints require a JSON payload. When sending a request in Postman, it automatically detects when the raw JSON body option is selected and adds the header Content-Type: application/json to the request. This adds the payload to the HTTP request json field.

Confirm that the payload is being sent in the request's json field when sending requests via other means. Without the Content-Type: application/json header, the payload might be stored in the data or form field and cause the request to fail since the json field where the expected data is null.

cURL

Add the Content-Type: application/json header to tell the request the --data-raw data is a JSON and should be stored in the request's json field.

Python

With the Python requests module, add the JSON payload to the json parameter when making a request, and the requests module will automatically send the Content-Type: application/json header with the request.

This method generates a JWT token ONLY when the user's authentication provider is set to PlexTrac and MFA is NOT enabled. For MFA, see the section.

is the basic auth endpoint and returns the following after successfully verifying the given username and password for a user without MFA:

Users with MFA enabled must use two endpoints to generate a JWT token. First, call the endpoint. The response will contain the code field if the user has MFA enabled. The value relates to the Authenticator set up by the user and the six-digit rotating code associated with their login.

Next, call the endpoint with the code returned from the last request and the current six-digit code from your Authenticator in the payload.

Tokens can be refreshed with the endpoint before the session expires, creating a new session that lasts another 15 minutes. The alternative approach is using the same authentication methods that generated the session in the first place. The advantage of refreshing a token vs. generating a new session is tied to how a user is authenticated into the latest session.

POST Authentication
POST Authentication
POST Multi-Factor Authentication
PUT Refresh Token
Generate Access Token (MFA)
response JSON for a POST Authenticate request
response JSON for a POST Authenticate request when MFA is setup
response JSON for a POST Multi-Factor Authentication request