Two-factor authentication

You can require a time-based one-time password (TOTP) as a second factor on top of whichever sign-in method the user chose. When it is on, completing a magic link or an OAuth sign-in is no longer enough on its own. The user also has to enter a six-digit code from an authenticator app such as Google Authenticator, 1Password, or Authy. The setting is per environment and applies to all sign-in methods at once. You cannot require a second factor for Google but not for magic links.

Turn it on

Step 1: In the dashboard, click Configure in the left sidebar, under Authentication, and select the environment. Step 2: In the TOTP section, turn on Require TOTP. Step 3: Set TOTP issuer to your product name. This is the label the user sees next to the code in their authenticator app, so make it recognizable.

TOTP section showing the Require TOTP toggle and the TOTP issuer field

Both settings are required. If Require TOTP is on but TOTP issuer is empty, Portal treats the environment as not requiring a second factor and completes sign-ins without one. Always set an issuer when you enable the toggle.

With two-factor off, a validation response carries the Client Session Token and the sign-in is done. With it on, that same response comes back with clientSessionToken set to null and a userJwt instead. There are three possible shapes. Branch on clientSessionToken:

Two-factor not required
Required, user enrolled
Required, first sign-in

{
  "data": {
    "endUserId": "clx1enduser00000000000000",
    "clientSessionToken": "b7c1f0a2-3d4e-5f60-8a91-2b3c4d5e6f70",
    "userJwt": null,
    "totpLink": null
  },
  "metadata": null
}

The sign-in is complete. Use clientSessionToken to initialize a Portal SDK.

{
  "data": {
    "endUserId": "clx1enduser00000000000000",
    "clientSessionToken": null,
    "userJwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.userjwt",
    "totpLink": null
  },
  "metadata": null
}

The user already has an authenticator set up. Prompt for their code.

{
  "data": {
    "endUserId": "clx1enduser00000000000000",
    "clientSessionToken": null,
    "userJwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.userjwt",
    "totpLink": "otpauth://totp/Example%20App:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example%20App"
  },
  "metadata": null
}

The user has no authenticator yet. Render totpLink as a QR code for them to scan, then prompt for their code.

Enrollment

totpLink is an otpauth:// URI, the standard format authenticator apps expect. Render it as a QR code. totpLink is returned only until the user’s first successful code entry. After that they are enrolled, and later sign-ins return userJwt with totpLink set to null. If a user abandons the sign-in before entering a code, they are still not enrolled and will get a totpLink again next time.

Validate the code

Send the userJwt as a Bearer token alongside your Auth Environment ID:

curl --request POST \
  --url https://api.portalhq.io/api/v3/auth/totps/validations \
  --header 'x-portal-auth-environment-id: <AUTH_ENVIRONMENT_ID>' \
  --header 'Authorization: Bearer <USER_JWT>' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "123456" }'

{
  "data": {
    "clientSessionToken": "b7c1f0a2-3d4e-5f60-8a91-2b3c4d5e6f70"
  },
  "metadata": null
}

This is the only endpoint in the Authentication API that takes two credentials. The Auth Environment ID identifies the environment and the userJwt identifies the half-finished sign-in.

Reset a user’s authenticator

If a user loses their device, reset their enrollment from the dashboard. Go to Authentication > End Users, open the user, and reset their TOTP enrollment. Their next sign-in returns a fresh totpLink so they can set up a new authenticator. See End users.

Getting Started

SDKs

APIs

Integrations

Resources

Two-factor authentication

Turn it on

Enrollment

Validate the code

Reset a user’s authenticator

Next steps

End users

API reference

​Turn it on

​What changes in your sign-in code

​Enrollment

​Validate the code

​Reset a user’s authenticator

​Next steps

End users

API reference

Turn it on

What changes in your sign-in code

Enrollment

Validate the code

Reset a user’s authenticator

Next steps