2 Factor Authentication

2fa can help massively to improve security on a website. It will slow down an attacker - maybe even stop.

Get 2FA Details

GET 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.

200 Successfully retrieved the user's 2fa details.

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

400 The API token provided is incorrect.

402 Your token does not have permission to use 2fa. Try contacting support or upgrade your plan.

404 The specified user was not found.

Enable 2FA

POST 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.

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.

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

400 The provided API token is incorrect

402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan.

404 The specified user was not found.

"issuer" will default to "Accountable" if not set.

Remove 2FA

DELETE 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.

204 2fa for the specified user was disabled.

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

400 The API token provided is incorrect.

402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan.

404 The specified user was not found.

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

POST 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.

200 The code was correct and the user can login.

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

400 Either the token was incorrect or you did not provide the required fields.

401 The provided code is incorrect. This could be due to the user being out of sync with the server.

402 Your token does not have permission to use 2fa. Try contacting support or upgrading your plan.

404 No user was found with the specified MFA token.

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.