# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://switchng.gitbook.io/switch/two-factor-auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.