# 2 Factor Authentication

## Get 2FA Details

<mark style="color:blue;">`GET`</mark> `https://accountable.pixelninja.dev/:token/user/:uuid/2fa`

This will give basic details about a user's 2fa status. This will include when it was enabled and their 2fa token. You can use this endpoint 10 times per second.

#### Path Parameters

| Name  | Type   | Description                                                    |
| ----- | ------ | -------------------------------------------------------------- |
| token | string | This is your API token.                                        |
| uuid  | string | This is the UUID of the user from who you are getting details. |

{% tabs %}
{% tab title="200 Successfully retrieved the user's 2fa details." %}

```c
{
    "enabled": true,
    "token": "PJOVGYTRLAWEKR22JQVHQI2REM7XQRSSJR5U4JKUEM3UIY2WKJ5Q",
    "enabledAt": 1621412871743
}
```

{% endtab %}

{% tab title="400 The API token provided is incorrect." %}

```c
{ "code": 400, "message": "Bad request" }
```

{% endtab %}

{% tab title="402 Your token does not have permission to use 2fa. Try contacting support or upgrade your plan." %}

```c
{ "code": 402, "message": "Payment required" }
```

{% endtab %}

{% tab title="404 The specified user was not found." %}

```c
{ "code": 404, "message": "Not found" }
```

{% endtab %}
{% endtabs %}

## Enable 2FA

<mark style="color:green;">`POST`</mark> `https://accountable.pixelninja.dev/:token/user/:uuid/2fa`

Enable 2fa for provided user. It will return a QR code data URI and the 2fa token (Not to be confused with an access token or MFA token) that can be used to calculate the time-based pin. This endpoint can be used 2 times per second.

#### Path Parameters

| Name  | Type   | Description                                     |
| ----- | ------ | ----------------------------------------------- |
| token | string | This is your API token.                         |
| uuid  | string | The UUID of the user who is having 2fa enabled. |

#### Request Body

| Name   | Type   | Description                                            |
| ------ | ------ | ------------------------------------------------------ |
| issuer | string | This is the name that will show in the user's 2FA app. |

{% tabs %}
{% tab title="200 2fa has been enabled successfully. You should now send the QR code to the client. The "token" does not need to be saved unless you plan to authenticate the 2fa yourself." %}

```c
{
    "token": "PJOVGYTRLAWEKR22JQVHQI2REM7XQRSSJR5U4JKUEM3UIY2WKJ5Q",
    "qrcode": "data:image/png;base64,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"
}
```

{% endtab %}

{% tab title="400 The provided API token is incorrect" %}

```c
{ "code": 400, "message": "Bad request" }
```

{% endtab %}

{% tab title="402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan." %}

```c
{ "code": 402, "message": "Payment required" }
```

{% endtab %}

{% tab title="404 The specified user was not found." %}

```c
{ "code": 404, "message": "Not found" }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
"issuer" will default to "Accountable" if not set.
{% endhint %}

## Remove 2FA

<mark style="color:red;">`DELETE`</mark> `https://accountable.pixelninja.dev/:token/user/:uuid/2fa`

Remove 2fa for the specified user. It will delete the stored 2fa token and set enabled to false. This endpoint can be used 3 times per second.

#### Path Parameters

| Name  | Type   | Description                                       |
| ----- | ------ | ------------------------------------------------- |
| token | string | This is your API token                            |
| uuid  | string | The UUID of the user whose 2FA you are disabling. |

{% tabs %}
{% tab title="204 2fa for the specified user was disabled. " %}

```c
{ "code": 204, "message": "No content" }
```

{% endtab %}

{% tab title="400 The API token provided is incorrect." %}

```c
{ "code": 400, "message": "Bad request" }
```

{% endtab %}

{% tab title="402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan. " %}

```c
{ "code": 402, "message": "Payment required" }
```

{% endtab %}

{% tab title="404 The specified user was not found." %}

```c
{ "code": 404, "message": "Not found" }
```

{% endtab %}
{% endtabs %}

## Authenticating With 2FA

What is 2FA if you can't actually use it to login? This section will cover how to check a user's 2FA PIN and managing the 2FA sign-in process.

## Authenticate 2FA PIN

<mark style="color:green;">`POST`</mark> `https://accountable.pixelninja.dev/:token/users/authenticate/2fa`

This endpoint takes an MFA token (which should have been assigned at login) and a 6 digit pin provided by the user. It will return telling you if the details match!

#### Path Parameters

| Name  | Type   | Description             |
| ----- | ------ | ----------------------- |
| token | string | This is your API token. |

#### Request Body

| Name  | Type   | Description                                              |
| ----- | ------ | -------------------------------------------------------- |
| token | string | This is the MFA token of the user who is authenticating. |
| code  | string | This is the 6 digit code they entered.                   |

{% tabs %}
{% tab title="200 The code was correct and the user can login." %}

```c
{ 
    "uuid": "d4b4e3d7-c081-4937-ae96-0ec140111f5b", 
    "accessToken": "ZDRiNGUzZDctYzA4MS00OTM3LWFlOTYtMGVjMTQwMTExZjVi.MTYyMTQxMjU3MTYyNg.xcvZeUyucHoj7TwWqZiTm4w8IpZsOWlz", 
    "code": 200 
}
```

{% endtab %}

{% tab title="400 Either the token was incorrect or you did not provide the required fields." %}

```c
{ "code": 400, "message": "Bad request" }
```

{% endtab %}

{% tab title="401 The provided code is incorrect. This could be due to the user being out of sync with the server." %}

```c
{ "code": 401, "message": "Unauthorized" }
```

{% endtab %}

{% tab title="402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan." %}

```c
{ "code": 402, "message": "Payment required" }
```

{% endtab %}

{% tab title="404 No user was found with the specified MFA token." %}

```c
{ "code": 404, "message": "Not found" }
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The MFA token is the token that is returned after authenticating the username and password, not the user's 2fa token that is returned when enabling 2fa.
{% endhint %}