Two-factor authentication

Turn it on for your account

1. Add an authenticator app

   Give the factor a name you'll recognise, like “Work phone”, and choose to add it.

2. Scan the QR code

   Scan it with your authenticator app. If you can't scan, type in the key shown under the code instead.

3. Confirm with a code

   Enter the six-digit code your app shows and choose Verify & turn on. Until you do, the factor stays Pending verification and isn't used.

From then on, every sign-in asks for a code after the password. You can add more than one factor, for example on a second phone, and remove one you no longer use from the same page.

Require it for everyone

Each person turns on two-factor authentication for themselves. To make it mandatory, or mandatory only for some people, deploy an MFA step-up action:

exports.onExecuteMfaStepUp = async (event, api) => {
  if (event.user.roles.includes('admin') || event.user.roles.includes('owner')) {
    api.authentication.requireMfa()
  }
}

When an action requires a second factor and the person hasn't enrolled one, the sign-in is refused with a message asking them to enroll first. Let them know before you deploy, so nobody is locked out.

Handle the code in your own app

If your app calls the sign-in API, a user with two-factor turned on gets a challenge back instead of tokens:

{
  "data": {
    "mfa_required": true,
    "mfa_token": "c1f0…",
    "available_factors": ["totp"],
    "challenge_id": "…"
  }
}

Ask the person for their code, then send it with the mfa_token. The token is valid for five minutes and works once.

curl -X POST https://id.trustportidentity.com/api/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{ "mfa_token": "c1f0…", "code": "492817" }'

A correct code returns the access and refresh tokens, the same as a sign-in without two-factor.

Manage factors with the API

Signed-in users can manage their own factors:

• POST /api/v1/mfa/factors/totp starts enrollment and returns the secret and a QR-code URI.
• POST /api/v1/mfa/factors/{id}/verify confirms it with a code.
• GET /api/v1/mfa/factors lists factors; DELETE /api/v1/mfa/factors/{id} removes one.

Other factors

Passkeys and security keys Coming soon are on the way. Until then, authenticator apps are the supported second factor.