nOTP APIs
Overview
The nOTP (no-tee-pee) APIs require two phases. The first phase calls the API endpoint to initiate the process (sign-up, sign-in, etc.), and the second phase presents the user with the QR code received from the first step.
On success, the first phase returns a QR code image and a redirect URL in the response. Either display the QR code to the user or redirect them to the URL. Once the user scans the code or is redirected, WhatsApp opens with an auto-filled message containing a token. After the user sends the message, the pendingRef from the initial API call can be used to retrieve the session.
Use Cases
- Sign up a new user
- Sign in an existing user
- Sign in with auto sign-up if the user does not exist
- Get Pending Session
Examples
Example - user sign-up with QR code
- Trigger the process with the Sign-Up endpoint. On success, the response body includes an
imageproperty (the QR code) and apendingRefproperty. - Display the image to the user. Once they scan it and send the pre-filled message, they are authenticated.
- Verify the user's state with the Get nOTP Pending Session endpoint, using the
pendingReffrom step 1.
Example - user sign-in with redirect URL
- Trigger the process with the Sign-In endpoint. On success, the response body includes a
redirectUrland apendingRefproperty. - Redirect the user to the provided URL. Once they send the pre-filled message, they are authenticated.
- Verify the user's state with the Get nOTP Pending Session endpoint, using the
pendingReffrom step 1.
Note
These examples apply to all sign-up, sign-in, and sign-in with auto sign-up use cases when using the relevant API endpoints.
Add / Update Key POST
### Add or update TOTP key for existing end user Initiate a flow to add TOTP functionality for an existing end user, or to update the TOTP key for an existing 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 Add / Update TOTP flow has successfully completed. The bearer token requires both the ProjectId and refresh JWT in the format `<Project ID>:<JWT>`, and can therefore only be run for end users who are currently signed-in. If the end user is not yet registered use the [Sign-Up](/api/totp/sign-up) endpoint to register the user. ### Next Steps 1. Display the TOTP key to the end user so the key can be entered into the authenticator app. Use any of the following methods to display the key to your end user: * (recommended) Redirect the end user session to the `provisioningURL` returned in the response body. The URL displays the key as a QR code that can be scanned directly from the authenticator app. * Render the QR code using your own web page using the `image` (the QR code as Base64) returned in the response body. * If your end user cannot scan a QR code, present the `key` returned in the response body so the key can be pasted into their authenticator app. If the authenticator app prompts, the end user must select key type: "time based". 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 Add / Update process. After successfully verifying the TOTP code the new TOTP key will be used to validate future TOTP code. ### 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.
Sign-Up POST
Create a new user using NOTP