Api.login

login(username, password)

Authenticates against the TrustID Cloud endpoint using the given username and password credentials.

Password Expiry

If the user’s password has expired, the password must be changed by using the Api.changePasswordAndLogin method instead in order to authenticate against the TrustID Cloud and change the password at the same time. In order for this to succeed, the correct username and existing (but expired) password must be presented alongside the new password which will take effect if the authentication via the existing password was successful.

This method executes asynchronously and returns a promise.

Arguments

  • username (string()) – The username to authenticate.

  • password (string()) – The password in cleartext to authenticate.

Returns

For error responses, see Error Responses. If the call succeeds, it returns the following data:

  • User (user) - details of the current account and its privileges. This is cached in Api.User.

  • Branch (branch) - details of the branch the current user is associated with (or null). This is cached in Api.Branch.

  • Config (configuration) - the instance of Config() that represents data about the current session and connected TrustID Cloud capabilities. This is cached in Api.Config.

Example response

var api = new TVS.Api();
api.login('admin', 'password').then(function() {
   // ...logged in...we can simply continue to use the api object...
   return api.getCustomFields();
}).then(function(customFields) {
   console.log('custom fields that are supported:', customFields);
});

If the authentication is successful:

  • session information is automatically retained within the instance of the Api() class and subsequent API calls are made with those session credentials until the session is terminated using Api.logout.

  • a lot of information about the session is provided through the response object as well as the Api() object itself. The response properties are shown above.

This method maintains accurate remaining credit information on the Api() instance, which can be obtained through the Api.RemainingCredits attribute.