Two-Factor Authentication

Securing users account using 2FA

STAGING_URL: https://switchapi3.azurewebsites.net
LIVE_URL: https://switchapi.azurewebsites.net

Set Pin

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/set_pin

This endpoint allows you to set your preferred pin.

Headers

Name	Type	Description
Authorization	string	Format for Authorization is Bearer token_string

Request Body

Name	Type	Description
pin	string	User's preferred 4 digits

200 Pin successfully set.

{
    "message": "PIN IS SET",
    "data": []
}

400 Could not find a cake matching this query.

{
    "message": "Pin should be a 4-digit number"
}

Send OTP

POST https://switch-api-staging.herokuapp.com/user/two_factor_auth/send_otp

This endpoint allows you to request OTP for your 2FA

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token_string

200

{
    "message": "OTP SENT",
    "data": []
}

Verify Phone Number

POST https://switch-api-staging.herokuapp.com/user/two_factor_auth/verify_phone

this endpoint allows you to request for verification of phone number for your 2FA

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token_string

Request Body

Name	Type	Description
otp	string	six digits code

200

{
    "message": "Phone verified",
    "data": []
}

400

{
    "message": "No OTP, OTP is expected"
}
OR 
{
    "message": "Invalid OTP"
}

Set Preferred 2FA type

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/set_two_factor_auth

This endpoint allows you choose your preferred 2FA type for your account

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token_string

Request Body

Name	Type	Description
new_two_fa_value	string	The otp for verification (if new_two_fa_type is google_authenticator and user.google_auth_set_up is false, i.e., the user has not set up google authenticator)
new_two_fa_type	string	The two_factor type the user is changing to. Can be either pin, phone or google_authenticator)
current_two_fa_value	string	The otp (if current_two_fa_type is phone or google_authenticator) or pin (if current_two_fa_type is pin). Required if the user has enabled his/her 2fa (i.e., if user.two_factor_authentication_enabled is true)

200

 {
    "message": "Two Factor Authentication type is set to: phone",
    "data": []
}

400

{
    "message": "Invalid Two Factor Type"
}

Update Pin

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/set_two_factor_auth

This endpoint allows you to update the user's pin.

Headers

Name	Type	Description
Authorization	string	Format for Authorization is Bearer token_string

Request Body

Name	Type	Description
new_two_fa_value	string	The new pin
new_two_fa_type	string	Must always be pin
current_two_fa_value	string	The user's current pin

200

{
    "message": "Pin Updated Successfully",
    "data": []
}

400

{
    "message": "Invalid PIN"
}

Security Questions

GET https://switchapi3.azurewebsites.net/user/two_factor_auth/security_questions

This endpoint retrieves all the security questions.

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token_string

200

{
    "message": "Security questions retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "What is your favorite color?"
        },
        {
            "id": 2,
            "name": "What is your first car?"
        },
        {
            "id": 3,
            "name": "What is your mother's maiden name?"
        }
    ]
}

Security Question

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/security_questions

This endpoint allows you to post the answer to a security question.

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token_string

Request Body

Name	Type	Description
security_question_answers	array	Array of objects (maximum of 3 security questions per user). Each object must contain the question_id and answer keys.

200

{
    "message": "Security question(s) have been set"
}

400

{
    "message": "Invalid format for security_question_answers"
}

Confirm email

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/confirm_email

This endpoint confirms the user email.

Request Body

Name	Type	Description
confirm_email_token	string	The confirm_email_token sent to the user's mail.

200

{
    "message": "Email confirmed"
}

400

{
    "message": "Email could not be confirmed",
    "errors": {
        "confirm_email_token": "is invalid"
    }
}

Update password

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/update_password

This endpoint updates the users password.

Headers

Name	Type	Description
Authorization	string	The format for Authorization is Bearer token

Request Body

Name	Type	Description
old_password	string	The old password.
new_password	string	The new password.

200

Get User's Security Questions

GET https://switchapi3.azurewebsites.net/user/two_factor_auth/user_security_questions

This endpoint retrieves the user's set security questions using the Authorization header, reset_password_token or reset_pin_token (listed in order of precedence).

Query Parameters

Name	Type	Description
reset_pin_token	string	Token sent to the user's mail when resetting pin.
reset_password_token	string	Token sent to the user's mail when resetting password.

Headers

Name	Type	Description
Authorization	string	Format is Bearer token.

200

{
    "message": "User's set security questions retrieved successfully",
    "data": [
        {
            "id": "1",
            "name": "What is your mother's maiden name?"
        },
        {
            "id": "2",
            "name": "What is your first car?"
        },
        {
            "id": "3",
            "name": "What is your favorite color?"
        }
    ]
}

400

{
    "message": "Expired token"
}

Forgot Pin

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/forgot_pin

This endpoint triggers the sending of the pin-reset mail to the user.

Headers

Name	Type	Description
Authorization	string	Format is Bearer token

200

{
    "message": "A reset-pin email has been sent to your mail"
}

Reset Pin

POST https://switchapi3.azurewebsites.net/user/two_factor_auth/reset_pin

This endpoint is used for re-setting the user's pin (in the scenario that the user forgets his/her pin).

Request Body

Name	Type	Description
reset_pin_token	string	The token from the reset-pin mail sent to the user.
security_question_id	string	The id of the security question.
security_question_answer	string	The answer to the security question.
pin	string	The new pin.

200

{
    "message": "Pin reset successfully"
}

401

{
    "message": "Invalid token"
}