Two Factor Authentication

TFA and Login

Get two factor auth(tfa) secret and qr-code

The user needs to be logged it. They need to have qt-auth cookie. A GET call is made to /api/auth/v1/two-factor-auth-token, this api returns

  • qr-code-url: The url for qr-code
  • auth-token: This token can be used to set app in autentication app, if qr-code cannot be scanned
  • secret-key: The key used to valid tfa code

Usage

Sample CURL

curl -X GET \
http://<publisher-website-url>/api/auth/v1/two-factor-auth-token \
-H 'Cookie: qt-auth=<jwt-token>' \
-H 'Host: localhost:9001'

Response

Status: 200
Body: {
"qr-code-url": "http://chart.apis.google.com/chart?cht=qr&chs=300x300&chl=${xyz}&chld=H|0",
"auth-token": "123456",
"secret-key": "FU7UCYTPFJ6HYSGFS"
}

Enable two factor auth(tfa)

The user needs to be logged in. They need to have qt-auth cookie. A POST call is needed made to /api/auth/v1/enable-two-factor-auth, with body containing keys

  • otp: The code from the authentication app, where the app is set
  • secret-key: The key used to valid tfa code, that was returned by /api/auth/v1/two-factor-auth-token

Usage

Sample CURL

curl -X POST \
http://<publisher-website-url>/api/auth/v1/enable-two-factor-auth \
-H 'Cookie: qt-auth=<jwt-token>' \
-H 'Host: localhost:9001'\
--data-raw '{"secret": "FU7UCYTPFJ6HYSGFS", "otp": "228072"}'

Response

Status: 200
Body: { message: "User TFA has been updated." }

Reset two factor auth(tfa) - Admin

The request needs to have Admin Access Token. A POST call is needs made to /api/auth/v1/admin/reset-two-factor-auth, with body containing keys

  • token: Admin Access Token as generated by /admin/access-token/integrations/<id> api
  • user: object containing either user-id (as id) or email (as email)

Usage

Sample CURL

curl -X POST \
http://<publisher-website-url>/api/auth/v1/admin/reset-two-factor-auth \
-H 'Host: localhost:9001'\
--data-raw '{"user": { "email": "foo@bar.com" }}'

Response

Sample response when two factor authentication for an user has been reset

Status: 204

Sample response when invalid token is sent

Status: 401
Body: { "message": "Invalid Token" }

Sample response when token has expired

Status: 401
Body: { "message": "Token expired" }

Login

If the user had enabled tfa, then instead of logging the user in or setting the session cookies. The login api returns

  • user-id: Encoded user-id
  • tag: Stringified buffer for decoding user data
  • salt: Timestamp

Sample CURL

curl -X POST \
http://<publisher-website-url>/api/auth/v1/login \
-H 'Host: localhost:9001'\
--data-raw '{"username": "Somename", "password": "password"}'

Response

Status: 200
Body: {
"user-id": "n123",
"tag": "7c0ae2f5bbc212fd99b2b79981995412",
"salt": "1594643573122"
}

TFA Callback

When the login returns the encoded data, then POST call is to be made to /api/auth/v1/tfa-callback

  • user-id: Encoded user-id
  • tag: Stringified buffer for decoding user data
  • salt: Timestamp
  • otp: The code from the authentication app, where the app is set

Usage

Sample CURL

curl -X POST \
http://<publisher-website-url>/api/auth/v1/tfa-callback \
-H 'Host: localhost:9001'\
--data-raw '{"user-id":"d498","tag":"7c0ae2f5bbc212fd99b2b79981995412","salt":"1594643573122","otp": "171391"}'

Response

Status: 200
Body: {
"message": "Successfully logged in",
"user": `User Details`,
"active-sessions-count": 1,
"member": `User Details`
}