Getting Started
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 interacting with the PlexTrac platform or manually making an API request.
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 is enforced to prevent brute force attacks against the platform. This limit may be reached naturally if multiple users attempt to sign in simultaneously or if an API script attempts to be used concurrently.
Generate Access Token
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 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.
Users with MFA enabled must use two endpoints to generate a JWT token. First, call the POST Authentication
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 POST Multi-Factor Authentication endpoint with the code returned from the last request and the current six-digit code from your Authenticator in the payload.
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:
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.
Last updated