One-Time-Password APIs
Overview
The One-Time-Password APIs require two phases. The first phase calls the API endpoint to initiate the process (sign-up, sign-in, etc.), and the second phase verifies the OTP code received by the user.
Each first-phase endpoint, on success, delivers a code to the user via email, voice call, or text message (SMS). Your app should then wait for the user to supply the code and call the verify endpoint (second phase) to confirm it and complete the action.
The OTP code can be delivered over email, voice call, or text message (SMS) — each has its own set of API endpoints.
Use Cases
- Sign up a new user (Email, SMS, Phone)
- Sign in an existing user
- Sign in with auto sign-up if the user does not exist
- Update user's email address
- Update user's phone number
Examples
Example - user sign-up over email
- Trigger the process with the Sign-Up endpoint. On success, the OTP code is delivered to the user's email.
- Complete the process by verifying the code with the Verify OTP Code endpoint. Once confirmed, the endpoint returns the user's session and refresh JWTs.
Note
This example also applies to the "Sign in an existing user" and "Sign in with auto sign-up" use cases, and to the text message (SMS) channel, when using the relevant API endpoints.
Example - update user's phone number
- Trigger the process with the Update Phone Number endpoint. On success, the OTP is delivered to the new phone number.
- Complete the process by verifying the code with the Verify Code API endpoint. Once confirmed, the user's phone number is updated, and all future OTP codes over SMS are delivered to the new number.
Note
This example also applies to the "Update user's email address" use case, when using the relevant API endpoints.
OpenAPI Specification
Download the Descope OpenAPI (Swagger) specification to import into Postman, generate clients, or browse with any OpenAPI tool.
Sign-Up POST
### Sign-up new end user by sending an OTP code via email Initiate a sign-up process by sending a One-Time Password (OTP) to a new end user. Descope will generate and deliver the OTP code to the email address specified. Sending multiple OTP codes (for example, when an end user tries to sign-up a second or third time) will invalidate any OTP code that has already been sent. This endpoint will return an empty response object when it completes successfully. The endpoint will return a failure code if the email address is already registered. ### Next Steps Verify the OTP code using the [Verify OTP Code](/api/otp/email/verify-otp) endpoint to complete the user sign-up process. After successfully verifying OTP code the end user will be signed-in. ### 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 [Sign-In](/api/otp/email/sign-in) endpoint to sign-in an existing end user. - Use the [Sign-In with Auto Sign-up](/api/otp/email/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered.