Authenticator App (TOTP)
Overview
Using the Authenticator App (TOTP) APIs enables users to sign in with an authenticator app. First you will need to provision the user with a secret seed - either by signing up a new user, or updating an existing user.
For signing up a new user, or updating an existing user with an authenticator app, first call the "Sign-Up" or "Add / Update" API endpoints. These endpoints will generate and provide a seed for the user to configure in the Authenticator App. Once the user configured the app, the "Sign-In / Verify" endpoint should be used to confirm the TOTP code, and complete the setup process.
Once a seed is configured for users, they can sign in with the code (TOTP) that the Authenticator App is generating. Use the "Sign-In / Verify" API Endpoint to sign users in with their loginId and the generated code.
Use Cases
- Sign up a new user
- Add or update an authenticator app for an existing user
- Sign in a user
Examples
Example - user sign-up over email
- Trigger the process with Sign-Up endpoint This will provide the Authenticator App secret seed (a code, or an image in BASE64 encoding)
- Compete the process by verifying the code with Sign In / Verify endpoint When the code is received from the end user, use the Sign In / Verify API to confirm the code. Once confirmed - the process will be completed, and the user will be signed up with the Authenticator App. The Sign In / Verify command will also return the user's Session and Refresh JWT tokens.
Note
This example applies also for the "Add or update an authenticator app for an existing user" use cases.
Example - Sign in a user
- The sign in user is a single-action process with the Authenticator App TOTP code.
Call the Sign In / Verify endpoint with the users loginId and the TOTP code provided by the user to sign the use in. This API endpoint will return a signed in user, with Session and Refresh JWT tokens,
Finishes a full OAuth flow using native APIs POST
Finishes a full OAuth flow using native APIs ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID>`
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. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID>`