Getting Started
Overview
The SecurityTrax API is generally RESTful, following the json:api specifications, with a few variances. Use of the API requires a valid user account and integrator key.
Integrator Key
You’ll need an integrator key to communicate with the APIs. If you don’t have one already assigned click here to request one. This case-sensitive key will be provided as the X-SecurityTrax-IntegratorKey in every request header.
You will be provided with an integrator key for our staging environment initially. Once you are ready to move to production, and your integration has been reviewed by SecurityTrax, you will be assigned a production key.
Authentication
To authenticate with the API you will need to pass a bearer token in the header. There are 2 ways to obtain this token.
1) Send a POST request to the /authenticate endpoint with a username and password in the body.
{
"username": "{{username}}",
"password": "{{password}}"
}
This will return a temporary token that can be used for subsequent requests. Note: this token will expire after 10 minutes.
2) Obtain a Personal Access Token (PAT). This permanent token does not expire and can be used as the bearer token in all requests. PAT's have special considerations that should be discussed with SecurityTrax.
Environments
We have two primary environments: staging and production. It is important to understand which environment you are working with as there are different resources for each one.
Staging
The staging environment will be your sandbox as you learn to use our APIs. This environment will allow developers to interact with a test system to ensure their application is working as designed before moving to production. You will have full access to the APIs and freedom to experiment as you write your app.
When you are assigned your staging integrator key you will be provided with credentials to the Sandbox Company test system. The Sandbox Company is the only company available in the staging environment.
Note: The sandbox site is a shared environment. Please to not use this environment for sensitive information.
API Services URL:
Direct all web service calls to this root URL.
https://api.staging.securitytrax.com/sandbox/user/v1/
Web Application URL:
Use this URL to log into the SecurityTrax application. From here you can see if the work you are performing is having it's intended impact.
https://app.staging.securitytrax.com/sandbox/login
Swagger Docs URL:
Use this URL to lookup details of each endpoint and how to use them.
Production
Our production environment is where live company data resides. In order to use your tools against production you will need to know company specific information. The company you are working with will need to provide this information to you.
- Profile Name. Each company working with SecurityTrax will have a unique profile name. This is the key that identifies the company and it can be found at the end of the URL the company uses to access SecurityTrax. For example:
https://app.securitytrax.com/sandbox. In this case sandbox is the company profile name. Simply ask the company the URL they use to access SecurityTrax to get their assigned profile name. - Credentials. Each company creates and manages all user accounts in their systems. This includes the credentials needed to access the application as well as the permissions that grant access to the different resources within SecurityTrax. You will need to work with the company in order to get your user account details. SecurityTrax cannot edit user accounts or permissions in company systems.
API Services URL:
Direct all web service calls to this root URL. Change the company-profile-name to the profile name of the site you are accessing.
https://api.securitytrax.com/{{company-profile-name}}/user/v1
Web Application URL:
Use this URL to log into the SecurityTrax application. From here you can see if the work you are performing is having it’s intended impact.
https://app.securitytrax.com/{{company-profile-name}}/login
Swagger Docs URL:
Use this URL to lookup details of each endpoint and how to use them. In this case no company specific profile is needed as the docs are the same for all companies.