Api only rails app OTP and multi-factor setup for Accounts

[hukic-m]

Hey all would appreciate some guidance to any docs or anything like that that will point me to setting up OTP's as Second Factor for api only rails application.

I've setup the JWT auth and it works great.
I have the routes for OTP ready

 POST  /auth/otp-auth                rodauth.otp_auth_path
 POST  /auth/otp-setup               rodauth.otp_setup_path
 POST  /auth/otp-disable             rodauth.otp_disable_path

Table setup

 create_table :account_otp_keys, id: false do |t|
    t.bigint :id, primary_key: true
    t.foreign_key :accounts, column: :id
    t.string :key, null: false
    t.integer :num_failures, null: false, default: 0
    t.datetime :last_use, null: false, default: -> { "CURRENT_TIMESTAMP" }
  end
  

After the setup I would be more than happy to update the postman docs for the JSON API with required params and everything.
Thank you 😄

[janko]

A POST /otp-setup request without parameters will give you valid otp_secret and otp_raw_secret params:

POST /otp-setup
Content-Type: application/json
Accept: application/json

422 Unprocessable Entity
Content-Type: application/json

{
  "otp_secret": "xp5yskxyvfstljx2nsa5z534s5r633gs",
  "otp_raw_secret": "jy4z3hmfhzflsqemmnnjd54p2kvgwlap",
  "field-error": ["otp_secret","invalid secret"],
  "error": "Error setting up TOTP authentication"
}

You can then make another POST /otp-setup request with the given otp_secret and otp_raw_secret, as well as password and otp containing the one-time code generated from otp_secret (e.g. via rotp --secret <otp_secret>).

POST /otp-setup
Content-Type: application/json
Accept: application/json

{
  "otp_secret": "xp5yskxyvfstljx2nsa5z534s5r633gs",
  "otp_raw_secret": "jy4z3hmfhzflsqemmnnjd54p2kvgwlap",
  "otp": "490273",
  "password": "secret123"
}

200 OK
Content-Type: application/json

{ "success": "TOTP authentication is now setup" }

When the user is logging in, you can then authenticate via TOTP by calling POST /otp-auth with otp parameter:

POST /otp-auth
Content-Type: application/json
Accept: application/json

{ "otp": "538423" }

200 OK
Content-Type: application/json

{ "success": "You have been multifactor authenticated" }

Finally, TOTP authentication can be disabled by calling POST /otp-disable and passing the password parameter.

[hukic-m]

Great thank you for the answer! 😄