Setting up time-based one-time passcodes (TOTP)

Time-based one-time passcodes (TOTP) are a passwordless two-factor authentication option that can be used when you need high security assurance. TOTP authentication solutions are ideal for particularly sensitive use cases that are also highly attractive in terms of the potential payoff they offer – think money movement in fintech or cryptocurrency, or access to a company’s HR or payroll information. When integrated as a second authentication factor, TOTP serves as an additional safeguard by requiring users to prove possession of their device. It works by generating a one-time passcode that’s based on the current time and a shared secret between an authenticator app like Google Authenticator or Authy, and the server (in this case, Stytch). Users, who must have an authenticator app downloaded on their device, are asked to input the unique passcode within a certain period of time, usually 30 seconds, as evidence of their identity. Once the user supplies the TOTP code, your app can use Stytch’s /totps/authenticate endpoint to verify that passcodes are valid and ultimately grant users access.

If the user attempting to register isn’t already associated with a Stytch user_id, you’ll need to create a Stytch User with the /users/create endpoint. Pass the user’s email address or phone number into the User create endpoint and store the returned user_id. The user_id will be used to register and authenticate with TOTP.

curl --request POST \
  --url https://test.stytch.com/v1/users \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "sandbox@stytch.com"
  }'

Next, you’ll want to create a TOTP for the user by passing the user_id into the /totps/create endpoint. This endpoint also takes in an expiration_minutes value; this value is the expiration for the TOTP instance. The newly create TOTP instance must be authenticated at least once within this timeframe otherwise it will expire and be render unusable. Make sure to expeditiously prompt the user to complete the TOTP flow quickly after TOTP creation. Defaults to 1440 (1 day) with a minimum of 5 and a maximum of 1440 (1 day).

This endpoint returns four unique fields in addition to the stand fields like status_code and request_id. The secret is shared between the authenticator app and your server. The totp_id is the Stytch identifier for a given TOTP instance. The qr_code is the base64-encoded representation of the QR code image. You can embed this directly into your website and it will display as a QR code that users can scan. And finally recovery_codes, if the user loses access to their authenticator app, they can input these recovery codes into the /v1/totps/recover endpoint at any point. If the recovery code is valid, then the recover endpoint will return a 200, and you, the developer, can choose to delete the TOTP instance and generate a new one or simply display the secret back to the user. Note that 10 recovery codes are generated, and each one can only be used once.

curl --request POST \
  --url https://test.stytch.com/v1/totps \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "expiration_minutes": 60,
  }'

Make sure that the user authenticates their first TOTP immediately after creating the TOTP so that the TOTP instance does not expire. When the user sends you the TOTP code, you will hit the /totps/authenticate endpoint with the user's user_id and the supplied totp_code to authenticate it.

In this step, to accomodate for network and user action delays, TOTP codes from the previous and next 30-second periods are allowed by this endpoint. If you’d like to begin a new Stytch session or re-use an existing one, you may pass in session_duration_minutes(to begin a new session) or session_token(to re-use an existing one). Please check out our session management guide for more information.

curl --request POST \
  --url https://test.stytch.com/v1/totps/authenticate \
  -u 'PROJECT_ID:SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
      "user_id": "user-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6",
      "totp_code": "576831",
  }'

You just finished all the critical components to add a second factor of authentication via TOTP! Have any feedback after having integrated TOTP? Get in touch with us and tell us what you think in our forum, support@stytch.com, or in our community Slack.