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

  1. 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.
  2. 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: domain\group\userName.
      2. In the Password field, enter your Windows password.

      You cannot log in to Track-It! using your Windows local account.

  3. 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:

<appSettings>
  <add key="DSN" value="Track-It" />
  <add key="DbLogInMaxRetries" value="1" />
  <add key="DbLogInRetryInterval" value="20" />
  <add key="CorsOrigins" value="*" />
  <add key="RefreshTokenLifeSpan" value="60" />
  <add key="AccessTokenLifeSpan" value="30" />
Was this page helpful? Yes No Submitting... Thank you

Comments