Authenticator App (TOTP)
Overview
The Authenticator App (TOTP) APIs enable users to sign in with an authenticator app. To get started, provision the user with a secret seed — either by signing up a new user or updating an existing user.
To sign up a new user or add an authenticator app to an existing user, call the Sign-Up or Add/Update API endpoints. These endpoints generate a seed for the user to configure in their authenticator app. Once the user has configured the app, call the Sign In / Verify endpoint to confirm the TOTP code and complete setup.
Once a seed is configured, users can sign in with the code (TOTP) generated by their authenticator app. Use the Sign In / Verify endpoint with the user's loginId and the generated code.
Use Cases
- Sign up a new user
- Add or update an authenticator app for an existing user
- Sign in / Verify a user
Examples
Example - user sign-up
- Trigger the process with the Sign-Up endpoint. This returns the authenticator app secret seed (as a code or a BASE64-encoded image).
- Complete the process by verifying the code with the Sign In / Verify endpoint. Once confirmed, the user is signed up with the authenticator app, and the endpoint returns the user's session and refresh JWTs.
Note
This example also applies to the "Add or update an authenticator app for an existing user" use case.
Example - sign in a user
Call the Sign In / Verify endpoint with the user's loginId and the TOTP code from their authenticator app. The endpoint returns the session and refresh JWTs.
Get Google One Tap Client ID Configuration GET
Get the client ID configuration for Google One Tap integration
Sign-Up POST
### Sign-up new end user via TOTP Initiate a TOTP sign-up process for a new end user. Descope will generate a TOTP key (also called a secret or seed) that will be entered into the end user's authenticator app so that TOTP codes can be successfully verified. The new end user will be registered after the full TOTP sign-up flow has successfully completed. If the end user is already registered use the [add/update](/api/totp/add-update-key) endpoint to add TOTP funtionality to an existing end user, to prevent the same person being registered twice. ### Next Steps 1. Display the TOTP key so it can be entered into their authenticator app. The TOTP key is returned in the response object in three ways, to ensure it can easily be entered into the end user's authenticator app. 2. Prompt the end user user for a TOTP code generated by their authenticator app. 3. Verify the TOTP code using the [Sign-In / Verify](/api/totp/sign-in-verify) endpoint to complete the sign-in process. After successfully verifying the TOTP code the new end user will be registered using the details you provided in the body of this endpoint. ### See Also - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number. - Use the [add/update](/api/totp/add-update-key) endpoint to add TOTP funtionality to an existing end user.