.auth

Authentication Module is responsible for all authentication functionality. Supported authentication mechanisms are:

  • Simple (Username/email & password)

  • Pin (quick login) using username & pin

  • SMS (OTP) using mobile number & OTP

On change of the session, i.e: user logs in or logs out, SessionStatus, a BehaviorSubject, is updated.

.login() ☆

To login using username/email and password. This method returns a SessionStatusInfo object.

On successful verification, the SessionStatus is updated with the current user.

Input

LoginParams

property

type

required

description

email

string

yes

The email or username of the user

password

string

yes

The password of the user

Output

SessionStatusInfo

Example

async-await

const authResponse = await renovationInstance.auth.login({
email: "test@abc.com",
password: "supercomplexpassword"
});
console.log("Successful login", authResponse.data.currentUser);

Classic Promise

renovationInstance.auth
.login({
email: "test@abc.com",
password: "supercomplexpassword"
})
.then(authResponse =>
console.log("Successful login", authResponse.data.currentUser)
);

Possible Errors

Incorrect credentials

HTTP code: 401

type: AuthenticationError

cause: Incorrect Password

suggestion: Enter the correct credentials

Non-existing user

HTTP code: 404

type: NotFoundError

cause: User disabled or missing

suggestion: Enter the correct credentials

By default cookies are used for session authentication. If JWT is required, call auth.enableJWT(true) before logging in.

.pinLogin() ★

This method is mostly used to quickly login, for instance POS. As with .login(), it returns SessionStatusInfo.

On successful verification, the SessionStatus is updated with the current user.

Input

PinLoginParams

property

type

required

description

username

string

yes

The username of the user

pin

string

yes

The pin of the user (all digits)

Output

SessionStatusInfo

Example

async-await

try {
const authResponse = await renovationInstance.auth.pinLogin({
user: "user1",
pin: "123456"
});
console.log("Successful login", authResponse.data.currentUser);
} catch (err) {
console.error("Logging in failed", err);
}

Classic Promise

renovationInstance.auth
.login({
user: "user1",
pin: "123456"
})
.then(authResponse =>
console.log("Successful login", authResponse.data.currentUser)
)
.catch(err => console.error("Logging in failed", err));

Possible Errors

Wrong PIN

HTTP code: 401

type: AuthenticationError

cause: Wrong PIN is entered

suggestion: Re-enter the PIN correctly

.sendOTP() ★

To get OTP using mobile number through SMS, this function can be used.

The SMS settings should be configured correctly in the backend before using this function.

This method does not authenticate the user. The next function .verifyOTP() will provide the option to authenticate the user and create a session.

Input

SendOTPParams

property

type

required

description

mobile

string

yes

The mobile number of the user

newOTP

boolean

no

Whether to generate a new OTP or reuse the existing one

Output

SendOTPResponse

Example

async-await

const authResponse = await renovationInstance.auth.sendOTP({
mobile: "+971000000000"
});
console.log("OTP sent", authResponse.data.status);

Classic Promise

renovationInstance.auth
.sendOTP({
mobile: "+971000000000"
})
.then(authResponse => console.log("OTP sent", authResponse.data.status));

Possible Errors

The errors depends mostly on the SMS provider setup in the backend and would be propagated through this function (API)

.verifyOTP() ★

To be used for verifying the OTP received after invoking .sendOTP().

On successful verification, the SessionStatus is updated with the current user.

Unlike .login(), this method will not return a SessionStatusInfo, instead a VerifyOTPResponse is returned.

Input

VerifyOTPParams

property

type

required

description

mobile

string

yes

The mobile number of the user

OTP

string

yes

The OTP received by through SMS

loginToUser

boolean

yes

Whether to generate a new OTP or reuse the existing one

Note: If loginToUser is set to false, the user is not logged in and SessionStatus is not updated. This can be useful in some applications like validating a change of mobile number.

Output

VerifyOTPResponse

Example

async-await

const authResponse = await renovationInstance.auth.verifyOTP({
mobile: "+971000000000",
OTP: "123456",
loginToUser: false
});
if (authResponse.success) {
console.log("OTP Verified", authResponse.data.status);
} else {
console.error("OTP Not Verified", authResponse.error);
}

Classic Promise

renovationInstance.auth
.verifyOTP({
mobile: "+971000000000",
OTP: "123456",
loginToUser: false
})
.then(authResponse => {
if (authResponse.success) {
console.log("OTP Verified", authResponse.data.status);
} else {
console.error("OTP Not Verified", authResponse.error);
}
});

Sample Response

{
"data": {
"status": "verified",
"mobile": "+971502760387"
},
"success": true,
"httpCode": 200
}

Possible Errors

Invalid Pin

HTTP code: 401

type: AuthenticationError

cause: Wrong OTP entered

suggestion: Enter correct OTP received by SMS or generate a new OTP

User not found / No Linked User

HTTP code: 404

type: AuthenticationError

cause: User is either not registered or does not have a mobile number

suggestion: Create user or add a mobile number

.checkLogin()

Checks the status of the login first locally and then verifies with the backend. SessionStatusInfo is returned.

Output

SessionStatusInfo

Example

async-await

const authResponse = await renovationInstance.auth.checkLogin();
if (authResponse.success) {
console.log("Logged In", authResponse.data);
} else {
console.error("Logged Out", authResponse.error);
}

Classic Promise

renovationInstance.auth.checkLogin().then(authResponse => {
if (authResponse.success) {
console.log("Logged In", authResponse.data);
} else {
console.error("Logged Out", authResponse.error);
}
});

Sample Response

{
"home_page": "/desk",
"message": "Logged In",
"user": "sample@user.com",
"full_name": "A Sample User",
"has_quick_login_pin": false
}

.getCurrentUserRoles() ★

Gets the roles of the current user logged in.

If the user is not logged in, the roles of Guest are loaded by default.

Output

string[]

Example

async-await

const userRoles = await renovationInstance.auth.getCurrentUserRoles();
if (userRoles.success) {
console.log("User Roles loaded", userRoles.data);
} else {
console.error("User roles failed", userRoles.error);
}

Classic Promise

renovationInstance.auth.getCurrentUserRoles().then(userRoles => {
if (userRoles.success) {
console.log("User Roles loaded", userRoles.data);
} else {
console.error("User roles failed", userRoles.error);
}
});

Sample Response

{
"success": true,
"httpCode": 200,
"data": [
"Translator",
"Renovation User",
"Blogger",
"All",
"Guest"
]
}

.logout()

Logs out the user locally followed by ending the session in the backend.

Output

any

Example

async-await

const response = await renovationInstance.auth.logout();
if (response.success) {
console.log("Logged out", response.data);
} else {
console.error("Error", response.error);
}

Classic Promise

renovationInstance.auth.getCurrentUserRoles().then(response => {
if (response.success) {
console.log("Logged out", response.data);
} else {
console.error("Error", response.error);
}
});

Sample Response

{
"success": true,
"httpCode": 200,
"data": {}
}

Even if the server's response is a failure, the user will need to re-login since the user is logged out in the front-end.

Reference

SessionStatusInfo

property

type

description

loggedIn

boolean

Whether the user is logged in

timestamp

number

The timestamp when the SessionStatusInfo was updated

currentUser

string

The current user logged in, if any

In addition, the interface contains an indexed property ([x: string]: any), containing information such as full_name.