Authentication¶

The TrustID Cloud requires authentication through username and password before any other calls can be made.

Note

The next two sections do not apply to the Javascript API; the Device and Session Identifiers are hidden in that API.

The Raw API endpoint /session/testConnection/ does not require user authentication.

Device Identifier (Raw API only)¶

All Raw API requests require the DeviceId property as part of the request message which is defined by the connecting client.

{
    "DeviceId": "device-id",
    ...
}

This can be chosen randomly but once a session identifier has been obtained by using a specific device identifier, that identifier cannot change during the lifetime of the session.

Note

Both the session identifier and the device identifier must be presented to the service whenever a request is made.

Two connecting devices cannot have the same device identifier.

Session Identifier (Raw API only)¶

While a device identifier is required for most endpoints, a session identifier can be omitted if the purpose of the endpoint is to obtain a session identifier.

Otherwise, the session identifier is required and must be presented together with the device identifier chosen for the lifespan of the session.

{
    "DeviceId": "device-id",
    "SessionId": "..."
}

In order to execute any meaningful operations, a session identifier must be obtained by authenticating against the TrustID Cloud.

The /session/login/ endpoint must be used to authenticate a user. As a result, a valid session identifier is provided. Subsequent calls to other endpoints must include this session identifier.

Login¶

The service endpoint authenticates against the TrustID Cloud using the username and password, for example:

Request

 POST {{server}}/VPE/session/login/
 Content-Type: application/json

{
    "DeviceId": "device-id",
    "Username": "admin",
    "Password": "********"
}

For endpoint details, see /session/login/.

var api = new TVS.Api();
api.login('admin', 'password').then(function() {
   // ...logged in...
});

After a successful login the API object retains the current session identifier that was obtained using Api.login. This means that we can simply continue to use the same API object without having to worry about the session data

The service should answer with the following Response message:

Response

{
    "Success": true,
    "Message": "Operation executed successfully.",
    "SessionId": "...",
    ...
}

For details of the additional information returned by the login endpoint, see Login Response and the /session/login/ endpoint reference.

 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);
});

For details of the additional information returned by the method, see Api.login.

Note

Once a valid session identifier has been obtained, it must be used for subsequent API calls together with the chosen device identifier.

Login Response¶

Apart from the session identifier, a login response contains a number of useful elements that can be relevant throughout the lifespan of the session. This information is mainly about the connected user and the configuration of the service they are connected to.

The following example shows more details of a typical login Response message:

Response

{
    "Success": true,
    "Message": "Operation executed successfully.",

    "SessionId": "...",

    "Configuration": [...],

    "User": { ... },
    "Branch": { ... },
    "Organisation": { ... },

    "DesktopClientDenied": false,
    "IncompatibleServiceVersion": false,
    "LockedUserAccount": false,
    "NewPasswordRequired": false,
    "RemainingCredits": null,
    "ServerApiVersion": "...",
    "VpeName": "Local Server"
}

For more details , see Login Response and the /session/login/ endpoint reference.

{
    Organisation: null,
    Branch: null,
    User: {
        Username: "username",
        ...
    },
    Config: {
        externalservices.available: true,
        supportingdocument.names: [...],
        ...
    }
}

User Information¶

User accounts can be organised within hierarchies. These may have three levels:

Organisations - these contain one or more branches.
Branches - each branch contains one or more users.
Users.

A hierarchy may instead have just two levels:

Branches - each branch contains one or more users.
Users.

Alternatively, no hierarchy at all may be used, leaving users independent of any branch.

When connecting to the TrustID Cloud, the following properties contain additional information about the connected user, branch and/or organisation:

LoginResponse.User

Represents information about the connected user who has successfully been authenticated against the system. See User for details of users.

LoginResponse.Branch

Contains information about the branch the current user belongs to (if any); otherwise null. See Branch for details of branches.

LoginResponse.Organisation

Contains information about the organisation the current user and branch belong to (if any); otherwise null. See Organisation for details of organisations.

User()

Represents information about the connected user who has successfully been authenticated against the system.

Branch()

Contains information about the branch the current user belongs to (if any), otherwise null.

Organisation()

Contains information about the organisation the current user and branch belong to (if any), otherwise null.

Configuration¶

The system may contain a list of key/value pairs that refers to a subset of the system’s configuration properties and can be useful, for example to determine if a particular feature is available or enabled.

{
    Configuration: [
        {
            "key": "autoDeleteEnabled",
            "Value": "False"
        }, {
            "key": "autoDeleteThresholdDays",
            "Value": "1"
        }
    ],
    ...
}

The property is LoginResponse.Configuration.

Configuration data values are stored as string values; see Configuration for more information.

var api = new TVS.Api();
api.login('admin', 'password').then(function(loginInfo) {
    // conventional: via login response
    console.log('loginInfo:', loginInfo);

    // information also available via API object...
    console.log('organisation:', api.Organisation);
    console.log('branch:', api.Branch);
    console.log('connected user:', api.User);
    console.log('config:', api.Config);
});

For details see Class Config.

API Versions¶

The Raw API property LoginResponse.ServerApiVersion may contain a version number of the protocol that is used to communicate with the TrustID Cloud. If a version number is given, the client can compare this with the expected version number of the protocol in order to identify protocol version mismatches.

VpeName¶

The Raw API property LoginResponse.VpeName may contain the display name of the TrustID Cloud that the client is connected to.

Password Reset¶

Individual user accounts can be marked so that the owner has to change the password on next login. If a user that is marked in this way tries to log in and the login attempt was otherwise successful, the response is a failure and the login response message contains the property shown below:

Response

{
    "NewPasswordRequired": true,
    ...
}

The marker is User.SetInitialPassword.

If LoginResponse.NewPasswordRequired is true as shown here, the user’s password must be changed before a valid session can be obtained again.

{
    "NewPasswordRequired": true,
    ...
}

If NewPasswordRequired is true as shown here, the user’s password must be changed before a valid session can be obtained again. See Api.changePasswordAndLogin.

To authenticate against the TrustID Cloud and provide the required new password at the same time, the following information must be sent as part of the login request message:

Request

POST {{server}}/VPE/session/login/
Content-Type: application/json

{
    "ChangePassword": true,
    "Username": "admin",
    "Password": "********",
    "NewPassword": "New$*Password43"
}

This will not only change the password for the user admin to New$*Password43 (assuming the current password matches) but also authenticate the user and provide a new session identifier.

var api = new TVS.Api();
api.login('username', 'password').then(function(loginResponse) {
    // ... login ok ...
}, function(loginResponse) {
    // ... login refused due to expired password? ...
    if (loginResponse.NewPasswordRequired) {
        // new password is required...
        return api.changePasswordAndLogin('username', 'password', 'new-password');
    }
}).then(function() {
    // ... password changed and logged in ...
});

For details, see Api.login and Api.changePasswordAndLogin.

Note

If your project is based around a server-to-server communication with the TrustID Cloud, where it is impractical to change the API user’s password, you could treat this as a login error, since the current password is no longer valid.

Logout¶

A session may expire after a certain period of time. However, you should terminate a session as soon as you do not require any further interaction with the TrustID Cloud. Terminate a session as shown below:

Request

POST {{server}}/VPE/session/logout/
Content-Type: application/json

{
    "DeviceId": "device-id",
    "SessionId": "..."
}

For endpoint details, see /session/logout/.

After executing this endpoint, the session identifier is rendered invalid. Subsequent API calls made using the same session identifier will fail until a new (valid) session is established.

var api = new TVS.Api();
api.login('admin', 'password').then(function() {
    // ...logged in...
    return api.getCustomFields();
}).then(function(customFields) {
    console.log('custom fields that are supported:', customFields);
}).then(function() {
    api.logout();
});

After the call of Api.logout the session that was captured by the API object is no longer valid. Subsequent API calls made on the same API object will fail until a new session is established.

Image Resources¶

For some API requests, including those for receiving image data, the current session identifier can be encoded within the URL. This enables embedding of image data using the img tag when HTML is used.

In this case, the URL shown below will receive an image resource.

The id argument refers to the unique identifier of the image, DeviceId and SessionId refer to the unique values that are specific to the current user session.

https://cloud.trustid.co.uk/vpe.svc/dataAccess/image/?id=…&DeviceId=…&SessionId=…

DeviceId and SessionId can be obtained from the API object after a session has been established successfully, for example:

var api = new TVS.Api();
api.login('username', 'password').then(function() {
    var img = document.createElement('img');
    var imageId = '... image identifier ...';
    var deviceId = api.getDeviceId();
    var sessionId = api.getSessionId();
    img.src = api.getUrl(
        '/dataAccess/image/' +
        '?id=' + imageId +
        '&DeviceId=' + deviceId +
        '&SessionId=' + sessionId
    );
    console.log('url:', img.src);
    document.body.appendChild(img);
});

For details, see Api.getDeviceId, Api.getSessionId and Api.getImageUrl.

To make this process easier, you can call a helper method of the API object to construct the full path to an image resource. This is shown below:

var api = new TVS.Api();
api.login('username', 'password').then(function() {
    var img = document.createElement('img');
    img.src = api.getImageUrl('... image identifier...');
    document.body.appendChild(img);
});

Note

By using a simple GET request, security-related properties such as the device identifier and session identifier may be exposed as GET arguments. If the connection is over HTTPS, all headers and GET arguments are encrypted but GET arguments may still appear in the web server log files and/or in the history of the browser.

The response may be an empty data stream if there is an error condition.

Authentication¶

Device Identifier (Raw API only)¶

Session Identifier (Raw API only)¶

Login¶

Login Response¶

User Information¶

Configuration¶

API Versions¶

VpeName¶

Password Reset¶

Logout¶

Image Resources¶

Cross Origin Resource Sharing (CORS)¶