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/.

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.

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.

User Information

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

  1. Organisations - these contain one or more branches.

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

  3. Users.

A hierarchy may instead have just two levels:

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

  2. 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.

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.

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.

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.

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.

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.

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.

See also

Retrieving Image Data for more information on how to access image data.

Cross Origin Resource Sharing (CORS)

When working within a web browser, Cross Origin Resource Sharing (CORS) might be relevant. For example, if your implementation or web app is hosted on https://www.example.com but you are accessing resources on https://cloud.trustid.co.uk using the Raw API, then CORS plays a part.

Note

CORS might only be relevant when executing Javascript within a Web Browser so this might only be of interest to those using the Javascript API.