Introduction

Welcome to the Trust Guard (TG) API!

You can use our API to access Trust Guard API endpoints, which can get information on various companies, users, scans & results in our database.

API Base URL

Environment	URL
Testing	`https://devapi.trust-guard.com`
Production	`https://api.trust-guard.com`

Notes

TG API using TLS 1.2 protocol for securities.
Use POSTMAN collection for reference API calls.

Getting Started

This chapter provides step-by-step instructions for using TrustGuard Third Party API and is divided in to the following sections:

Step 1. Web Portal: Obtaining API Key

Step 2. Server Request: Using API Key

Important Note

Web Portal: Obtaining API Key

First, login to trustguard portal.
After login, go to Management > API Account through the link on the left sidebar to go to API Account Management Page
To add a new user, press Add API Account button
Fill-in the fields then press Save
To obtain the API User's API Key press Edit Button
In the Edit API Account press the Show Button
A popup will show that will ask for your Password
Generate API Key text area will now be available which contains your API Key
Copy the generated API Key and save it for later use.

Server Request: Using API Key

An API Testing Tool such as Postman is required to interact with the API.

The API Key we generated will be used to obtain an ACCESS_TOKEN. This token is required to interact with the API.

Please refer to this section for instructions on how to obtain an ACCESS_TOKEN.

Errors

The Trust Guard API uses the following generic error codes:

Error Code	Meaning
200	Successful -- OK request.
201	Created -- Your requested resource created.
400	Bad Request -- Your request is bad.
401	Unauthorized -- Your API key is wrong or insufficient client credentials.
403	Forbidden -- You don't have access to requested resource.
404	Not Found -- The specified resource could not be found
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

API response will return errors array with errors in response.
API response will return messages array with success messages in response.

Token

Get Refresh Token

This is the way to get API account token to authenticated API calls with TG portal. Admin of TG company can create new API account from TG portal and get token of particular API account.

Steps

Login into TG portal.
Go to “API Account” side menu option and click on “Add API Account”.
Add required fields and save API account.
Go to edit API account page and generate REFRESH_TOKEN and copy it. It will require password of admin to access it.

Get Access Token

Request:

curl -X POST "<api_url>/partner-api/auth/renew"
  -H "Authorization: Bearer <REFRESH_TOKEN>"

Response:

{
  "accessToken": "<token>",
  "exp": "2019-07-29T09:32:51+00:00",
  "messages": ["success"],
  "success": true,
  "status": 200
}

exp - Expiry date of access token

messages - Messages array will include success messages

errors - Errors array will include error messages

This API allows you to get ACCESS_TOKEN for particular API account so API account can access TG APIs for various operations. This API needs API Account Token generated from TG portal “Add API Account” page.

HTTP Request

POST <api_url>/partner-api/auth/renew

Replace api_url with API base URL.

You must replace REFRESH_TOKEN with your API Refresh Token.

You need to use ACCESS_TOKEN from this API response in all other APIs as Authorization header. Access token is valid for 15 minutes of usage.

Scan

Get Recent Scans

Request:

curl -X GET "<api_url>/partner-api/scans?range=2month"
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response:

{
    "currentPage": 1,
    "totalPage": 40,
    "data": [
        {
            "cid": 26,
            "companyName": "Test Company",
            "did": 13195,
            "mid": "A0192",
            "device": "test.com",
            "name": "test.com",
            "frequency": "daily",
            "scanResultID": 254788,
            "status": "failed",
            "progress": 100,
            "pciStatus": "pass",
            "malwareScanStatus": "pass",
            "sslDate": "2021-02-01 23:59:59",
            "created": "2019-01-24 22:29:02",
            "finished": null,
            "high": null,
            "medium": 2,
            "low": 10,
            "total": 12
        }
    ],
    "messages": ["recent scans returned"],
    "success": true,
    "status": 200
}

This API allows you to get multiple scan results based on range and limit. This API will return all scan results from all companies under requested API account.

HTTP Request

GET <api_url>/partner-api/scans?range=2month

GET <api_url>/partner-api/scans?range=2month&page=1

GET <api_url>/partner-api/scans?from=2024-01-01&to=2024-01-20

Request Parameters

range

Results from NOW – interval.

?range=numberunit

i.e. 3month

unit values: • minute • hour • day • week • month • quarter

page

Offset of result. 1 page yields 100 results at most.

from | to

Results from DATE1 to DATE2.

?from=YYYY-MM-DD&to=YYYY-MM-DD

i.e. ?from=2024-01-15&to=2024-02-15

limit

The number of devices returned

SSO

Single Sign On

Request:

curl -X POST "<api_url>/partner-api/auth/signin"
  -H "Authorization: Bearer <ACCESS_TOKEN>"
  -d '{<json_request_parameters>}'

Response:

{
  "dashURL": "<dash_url>",
  "messages": ["success"],
  "success": true,
  "status": 200
}

This API is used to get access to TG client portal for users using single sign-on from third party portal.

HTTP Request

POST <api_url>/partner-api/auth/signin

Request Attributes

Attribute	Description	Type	Required
cid	Company Id assigned by TG	Number	true
uid	User Id assigned by TG	Number	true

Response Attributes

Attribute	Description	Type
dashURL	TG Client Dashboard URL for user to login	String

Company - New API

This chapter contains the latest information in creating new regular, trial, and freemium merchants

Important Setup

These are the required resellerID and apikey that needs to be secured before proceeding.

Reseller ID and Form API Key

resellerID - Assigned by TG. You can get it from Reseller Overview Page [Resellers > Overview] See image below:
apikey - Can be generated in Edit API Account page [Management > API Account > edit] See image below:

The apikey used here must not be confused with the API Key that is used in authorization and in renewing
the Access Key. This specific apikey can be generated in the API Account page under Form API Key See image above.

Create Trial Merchant

This api is used to create TRIAL merchant

Request:

curl -X POST "<api_url>/api/company.php/post_createtrialmerchant"

Response:

{
    "companyID": "X3Z0o9GRPL",
    "companyName": "Test Trial Merchant",
    "mid": "a10023",
    "adminName": "Trial Merchant Admin",
    "adminEmail": "admin@trialmerchant.com",
    "messages": ["company created!"],
    "success": true,
    "status": 200
}

HTTP Request

POST <api_url>/api/company.php/post_createtrialmerchant

Request Attributes

Attribute	Description	Type	Required
companyName	name of merchant	String	true
companyAddress	merchant address	String	true
companyCity	merchant city	String	true
companyCountry	merchant country	ISO 3166-1 alpha-2	true
companyZip	merchant zip	String	true
billingB2UID	for B2U purposes	String
resellerID	assigned by TrustGuard	String	true
mid	id of the merchant in your database	String
companyVAT	merchant VAT	String	true
companyCOC	merchant COC	String	true
customerName	admin name	String	true
customerEmail	admin email	String	true
customerPhone	admin phone number	String	true
customerLanguage	Prefered language. options: (en/nl)	ISO 639-1	true
apikey	FORM API KEY	String	true

Create Freemium Merchant

This api is used to create FREEMIUM merchant

Request:

curl -X POST "<api_url>/api/freemium.php/post_createmerchant"

Response:

{
    "companyID": "X3Z0o9GRPL",
    "companyName": "Test Freemium Merchant",
    "mid": "a10023",
    "adminName": "Freemium Merchant Admin",
    "adminEmail": "admin@freemiummerchant.com",
    "messages": ["company created!"],
    "success": true,
    "status": 200
}

HTTP Request

POST <api_url>/api/freemium.php/post_createmerchant

Request Attributes

Attribute	Description	Type	Required
customerName	admin name	String	true
customerEmail	admin email	String	true
customerPhone	admin phone number	String	true
customerUrl	admin phone number	String	true
resellerId	assigned by TrustGuard	String	true
companyName	name of merchant	String	true
customerLanguage	Prefered language. options: (en/nl)	ISO 639-1	true
customerCountry	merchant country	ISO 3166-1 alpha-2	true
mid	id of the merchant in your database	String
apikey	FORM API KEY	String	true

Create Regular Merchant

This api is used to create Regular merchant

Request:

curl -X POST "<api_url>/api/company.php/post_createmerchant"

Response:

{
    "companyID": "X3Z0o9GRPL",
    "companyName": "Test Regular Merchant",
    "mid": "a10023",
    "adminName": "Regular Merchant Admin",
    "adminEmail": "admin@regularmerchant.com",
    "messages": ["company created!"],
    "success": true,
    "status": 200
}

HTTP Request

POST <api_url>/api/company.php/post_createmerchant

Request Attributes

Attribute	Description	Type	Required
companyName	name of merchant	String	true
companyAddress	merchant address	String	true
companyCity	merchant city	String	true
companyCountry	merchant country	ISO 3166-1 alpha-2	true
companyZip	merchant zip	String	true
billingB2UID	for B2U purposes	String
resellerID	assigned by TrustGuard	String	true
mid	id of the merchant in your database	String
companyVAT	merchant VAT	String	true
companyCOC	merchant COC	String	true
customerName	admin name	String	true
customerEmail	admin email	String	true
customerPhone	admin phone number	String	true
customerLanguage	Prefered language. options: (en/nl)	ISO 639-1	true
apikey	FORM API KEY	String	true