nOTP APIs
Overview
Using the nOTP (no-tee-pee) APIs requires two phases. The first phase involves calling the API endpoint to initiate the process (sign-up, sign-in, etc.), and the second phase involves passing the user the QR Code received from the first step.
When successfully executed, the first phase API endpoint will result in a QR Code image and a redirect URL in the response. Either display the QR Code to the user or redirect him to the URL. Once the user scans the code or is redirected, he will be prompt with WhatsaApp and an auto-filled message with a token will be populated. Once the user sends the message, the pending ref from the initial API call can be used to retrive the session.
Use Cases
- Sign up a new user
- Sign in an existing user
- Sign in with auto sign-up a new user if not exists
Examples
Example - user sign-up with QR Code
- Trigger the process with Sign-Up endpoint Once successfully completed - the QR Code will be returned in the response body under the "image" property and a "pendingRef" property.
- Display this image to the user. Once he scans it, and sends out the pre-filled message, he will be authenticated.
- Verify the state of the user with Get NoTP Pending Session endpoint, using the "pendingRef" from the first step.
Example - user sign-in with Redirect URL
- Trigger the process with the Sign-In endpoint Once successfully executed - the redirect url will be returned in the response body under the "redirectUrl" and a "pendingRef" property.
- Redirect the user to the redirect url provided from the first step. Once he sends out the pre-filled message, he will be authenticated.
- Verify the state of the user with Get NoTP Pending Session endpoint, using the "pendingRef" from the first step.
Note
This examples apply for all "Sign Up", "Sign in an existing user" and "Sign in with auto sign-up a new user if not exists" 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. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID:Refresh JWT>`
Sign-Up POST
Create a new user using NOTP ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID>`