> For the complete documentation index, see [llms.txt](https://switchng.gitbook.io/switch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://switchng.gitbook.io/switch/two-factor-auth.md).

# Two-Factor Authentication

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

## Set Pin

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 Pin successfully set." %}

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

{% endtab %}

{% tab title="400 Could not find a cake matching this query." %}

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

{% endtab %}
{% endtabs %}

## Send OTP

<mark style="color:green;">`POST`</mark> `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&#x20;*****token\_string*** |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Verify Phone Number

<mark style="color:green;">`POST`</mark> `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&#x20;*****token\_string*** |

#### Request Body

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| otp  | string | six digits code |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="400 " %}

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

{% endtab %}
{% endtabs %}

## Set Preferred 2FA type

<mark style="color:green;">`POST`</mark> `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&#x20;*****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) |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="400 " %}

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

{% endtab %}
{% endtabs %}

## Update Pin

<mark style="color:green;">`POST`</mark> `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&#x20;*****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 |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Invalid PIN"
}
```

{% endtab %}
{% endtabs %}

## Security Questions

<mark style="color:blue;">`GET`</mark> `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*** |

{% tabs %}
{% tab title="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?"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Security Question

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}

{% tab title="400 " %}

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

{% endtab %}
{% endtabs %}

## Confirm email

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Email confirmed"
}
```

{% endtab %}

{% tab title="400 " %}

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

{% endtab %}
{% endtabs %}

## Update password

<mark style="color:green;">`POST`</mark> `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. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Get User's Security Questions

<mark style="color:blue;">`GET`</mark> `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***. |

{% tabs %}
{% tab title="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?"
        }
    ]
}
```

{% endtab %}

{% tab title="400 " %}

```
{
    "message": "Expired token"
}
```

{% endtab %}
{% endtabs %}

## Forgot Pin

<mark style="color:green;">`POST`</mark> `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*** |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Reset Pin

<mark style="color:green;">`POST`</mark> `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.                                        |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Pin reset successfully"
}
```

{% endtab %}

{% tab title="401 " %}

```
{
    "message": "Invalid token"
}
```

{% endtab %}
{% endtabs %}