Authenticating users with Web Services APIs

Before you can use the Track-It! Web Services APIs, you must authenticate your user.

Notes

You can use only Technician Track-It! credentials to authenticate.
You do not require ClientID and ClientSecret for authentication with Track-It! Web APIs.

You can authenticate users through either of the following methods:

- Using the Swagger interface to authenticate users
- Creating a Token Web API to authenticate users
  - Generating access token for Track-It!
  - Configuring access token validity

Using the Swagger interface to authenticate users

Navigate to http(s)://servernameOrIP/trackitvirtualdirectory/WebAPI in the browser.
This loads the Swagger interface, which provides a list of all available Web APIs and their input parameters. You can use the Swagger interface to test each Web API.
Select the Web API you want to execute and when prompted to authenticate, enter the following authorization credentials:
- For Username, enter GROUP\LOGINID
- For Password, enter your password
  Note
  Group and Login ID are both case-sensitive and need to be entered in all capital letters.
  Tip
  You can use your Microsoft Windows Domain Name, User Name, and Password to log in to the Track-It! Web API as follows:
  1. In the Login ID field, specify your Windows user name in the following format: group\domain\userName
  2. In the Password field, enter your Windows password.
  You cannot log in to Track-It! using your Windows local account.
Click Authorize.

Creating a Token Web API to authenticate users

The following table describes the Token Web API:

Description	Returns the Authorization Bearer access_token that authorizes the use of all Track-It! Web Services APIs
Type of call	POST
Request Authorization Header	None
URL Syntax	http(s)://servernameOrIP/trackitvirtualdirectory/WebApi/token
Request Parameters	None
Request Body	scope: grant_type: password username: <GROUP\LOGINID> password: <password>
Execution response	The following values are returned: Authorization Bearer token Bearer as token type Date and time of issue Expiration date and time of the token Expiration duration of the token in seconds Server language Technician information as follows: username usergroupname First Name Last Name Phone Extension EMail Address Alternate Phone, Priority hierarchy of the specific group
Important considerations	The access_token is used in all subsequent API requests for authorization and maintaining the session of a technician.

Example

http(s)://servernameOrIP / trackitvirtualdirectory/WebApi/token

Request Body:

scope:

grant_type: password

username: SYSTEM ADMINISTRATION\ADMINISTRATOR

password: trackit

Response:

{

"access_token":"ExPqpLF79Zi+vHZJIXZOGBSQVPKXlFVOfmQzMyfS7SGYJolrDAf3/LZR1qm9X+2OVY60OlEuUYOYaflcIjj7ytZ336b50mu4ieuPnx2AU2vCFgO3eqUe22Up",

"token_type":"bearer",

"expires_in":17999,

"refresh_token":"3c53ff0dc6f44b3a9071e861b8ef2022"....

}

Generating access token for Track-It!

To generate the authentication token from a custom code or custom application, you must supply the login parameters (grant_type, username, and password) in the form encoding format. For example, application/x-www-form-urlencoded.

You must set the content-type parameter to application/x-www-form-urlencoded in the request header.

You can use the following sample C# code to generate and test the access tokens in Track-It!:

var client = new RestClient("http://<trackitserver>/trackit/webapi/token");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "username=SYSTEM%20ADMINISTRATION%5CADMINISTRATOR&password=<password>&grant_type=password", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

You can use the following sample javascript code to generate and test the access tokens in Track-It!:

var data = "grant_type=password&username=SYSTEM%20ADMINISTRATION%5CADMINISTRATOR&password=<password>";

var XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
    console.log(this.responseText);
   }
});

xhr.open("POST", "http://<trackitserver>/trackit/webapi/token");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);

Configuring access token validity

The default validity period for the generated access token is 30 minutes. After the validity period has expired, you can regenerate the access token by calling the token API again.

You can configure the default validity period of access tokens in the Web API configuration file (Web.config). The following figure shows where you can modify the AccessTokenLifeSpan value: