Normal Login user flow

Successful Flow

APIs used
POST /authentication/login

Error Flows

Incorrect Pin

Incorrect Authentication Key

Incorrect PIN

This section describes the error codes in case the PIN used is incorrect

First Authentication Failure

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed",
                "code": "AN-AUTH-1006"
            }
        }
    

Second Authentication Failure

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed, You have 1 more login attempt before your device is locked for 5 minutes",
                "code": "AN-AUTH-1029"
            }
        }
    

Third Authentication Failure

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed, your device is now locked for 5 minutes",
                "code": "AN-AUTH-1030"
            }
        }
    

Authentication beyond locked device state (5 minutes)

The user will then be locked upon the third authentication failure for five minutes. Any other attempts to authenticate will be preempted by the following JSON response even if the credentials are correct

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "This device is temporarily locked, please try again later",
                "code": "AN-AUTH-1031"
            }
        }
    

Note: During the five minutes of which the device is temporarily locked, the user may reset the PIN if they wish.

Fourth Authentication Failure

Once five minutes has passed from the previous failed attempt that resulted in a temporary lock, they're then free to log in again and another failed authentication results in the following error message:

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed",
                "code": "AN-AUTH-1006"
            }
        }
    

Fifth Authentication Failure

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed, You have 1 more login attempt before your device is locked",
                "code": "AN-AUTH-1004"
            }
        }
    

Sixth & Last Authentication Failure

At this stage, the device is permanently locked & can only be unlocked by either contacting the organisation support staff or by unlocking it from another authenticated device.

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Authentication failed, your device is now locked",
                "code": "AN-AUTH-1005"
            }
        }
    

Any other attempts beyond the state of the device being permanently locked results in this response

        {
            "responseStatus": {
                "status": "ERROR",
                "message": "Device is locked",
                "code": "AN-HENG-1004"
            }
        }
    

Incorrect Authentication Key

This section describes the error codes in the case where the Authentication Key or authKey is incorrect. Sending a login request to the server with an incorrect authKey will result in the error code below

      {
            "responseStatus": {
                "status": "ERROR",
                "message": "Wrong authKey",
                "code": "AN-HENG-1001"
            }
      }
    

NOTE: If in the case the authKey has been lost we provide more information below to recover from that scenario

Network Resilience - Login user flow

Successful scenario

APIs used
POST /authentication/login
DELETE /device/{deviceUuid}/auth-key/{authKeyUuid}/others

Lost Auth Key scenario

APIs used
POST /authentication/login
DELETE /device/{deviceUuid}/auth-key/{authKeyUuid}/others

Lost Auth Key Confirmation scenario

APIs used
POST /authentication/login
DELETE /device/{deviceUuid}/auth-key/{authKeyUuid}/others