OTP Authentication

This authentication guide is meant for developers that are NOT using Descope to design login screens and authentication flows. If you’d like to use Descope Flows, Quick Start should be your starting point.

Introduction

A one-time password (OTP) is an automatically generated string sent to the user during the onboarding (sign-up or sign-in) process to authenticate that user. The OTP can be sent to an email address or a mobile phone as a text. A typical method for implementing OTP has two sets of functionality you need to program: user interaction and session verification.

Use Cases

New user signup: The following actions must be completed, first User Sign-Up then User Verification
Existing user signin: The following actions must be completed, first User Sign-In then User Verification
Sign-Up or Sign-In (Signs up a new user or signs in an existing user): The following actions must be completed, first User Sign-Up or Sign-In then User Verification

Install SDK

NodeJSPythonGoJavaRuby

npm i --save @descope/node-sdk

pip3 install descope

go get github.com/descope/go-sdk

// Include the following in your `pom.xml` (Maven)
<dependency>
    <artifactId>java-sdk</artifactId>
    <groupId>com.descope</groupId>
    <version>sdk-version</version> // Check https://github.com/descope/descope-java/releases for the latest versions
</dependency>

gem install descope

Import and initialize SDK

NodeJSPythonGoJavaRuby

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

from descope import (
    REFRESH_SESSION_TOKEN_NAME,
    SESSION_TOKEN_NAME,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    AssociatedTenant,
    RoleMapping,
    AttributeMapping,
    LoginOptions
)
try:
    # You can configure the baseURL by setting the env variable Ex: export DESCOPE_BASE_URI="https://auth.company.com  - this is useful when you utilize CNAME within your Descope project."
    descope_client = DescopeClient(project_id='__ProjectID__')
except Exception as error:
    # handle the error
    print ("failed to initialize. Error:")
    print (error)

import "github.com/descope/go-sdk/descope"
import "github.com/descope/go-sdk/descope/client"

// Utilizing the context package allows for the transmission of context capabilities like cancellation
//      signals during the function call. In cases where context is absent, the context.Background()
//      function serves as a viable alternative.
//      Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
import (
	"context"
)

// DescopeBaseURL // within the client.Config, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.

descopeClient, err := client.NewWithConfig(&client.Config{ProjectID:"__ProjectID__"})
if err != nil {
    // handle the error
    log.Println("failed to initialize: " + err.Error())
}

import com.descope.client.Config;
import com.descope.client.DescopeClient;

var descopeClient = new DescopeClient(Config.builder().projectId("__ProjectID__").build());

require 'descope'

@project_id = ENV['DESCOPE_PROJECT_ID']
@client = Descope::Client.new({ project_id: @project_id})

User Sign-Up

For registering a new user, your application client should accept user information, including an email or phone number used for verification. In this sample code, the OTP verification will be sent by email to "email@company.com". To change the delivery method to send the OTP verification as a Text Message (SMS), you would change the delivery_method to sms within the below example.

Note that signup is not complete without the user verification step below.

NodeJSPythonGoJavaRuby

// Args:
//    user: Optional user object to populate new user information.
const user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    deliveryMethod: Delivery method to use to send OTP. Supported values include "email" or "sms"
const deliveryMethod = "email"
//    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
const signUpOptions = {
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }

const resp = await descopeClient.otp.signUp[deliveryMethod](loginId, user, signUpOptions);
if (!resp.ok) {
  console.log("Failed to initialize signup flow")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully initialized signup flow")
}

# Args:
#   user: Optional user object to populate new user information.
user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}
#   login_id: email or phone - becomes the loginId for the user from here on and also used for delivery
login_id = "email@company.com"
#   delivery_method: Method used to deliver the OTP. Supported delivery methods - DeliveryMethod.SMS or DeliveryMethod.EMAIL
delivery_method = DeliveryMethod.EMAIL
#   signup_options (SignUpOptions): this allows you to configure behavior during the authentication process.
signup_options = {
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }

try:
  descope_client.otp.sign_up(method=delivery_method, login_id=login_id, user=user, signup_options=signup_options)
  print ("Successfully initialized signup flow")
except AuthException as error:
  print ("Failed to initialize signup flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

-------------- or (use a Python Decorator) --------------

from descope.flask import descope_signup_otp_by_email

# You can pass email in the request body of the endpoint
@app.route('/signup/email', methods=['POST'])
@descope_signup_otp_by_email(descope_client)
def signup_email():
    return "Signup email sent"

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    deliveryMethod: Delivery method to use to send OTP. Supported values include descope.MethodEmail or descope.MethodSMS
deliveryMethod := descope.MethodEmail
//    loginID: email or phone - becomes the loginId for the user from here on and also used for delivery
loginID := "email@company.com"
//    user: Optional user object to populate new user information.
user := &descope.User{
  Name: "Joe Person",
  Phone: "+15555555555",
  Email: loginID,
}
//    signUpOptions: this allows you to configure behavior during the authentication process.
signUpOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

err := descopeClient.Auth.OTP().SignUp(ctx, deliveryMethod, loginID, user, signUpOptions)
if (err != nil){
  fmt.Println("Failed to initialize signup flow: ", err)
} else {
  fmt.Println("Successfully initialized signup flow")
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();
var signUpOptions = SignupOptions.builder()
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

OTPService otps = descopeClient.getAuthenticationServices().getOtpService();
try {
  String maskedAddress = otps.signUp(DeliveryMethod.EMAIL, loginId, user, signUpOptions);

} catch (DescopeException de) {
  // Handle the error
}

# Every user must have a login ID. All other user information is optional
# For sign up either phone or email is required
email = 'desmond@descope.com'
user = {'name': 'Desmond Copeland', 'phone': '+15555555555', 'email': email}
masked_address = descope_client.otp_sign_up(method: Descope::Mixins::Common::DeliveryMethod::EMAIL

, login_id: 'someone@example.com', user: user)

User Sign-In

For authenticating a user, your application client should accept the user's identity (typically an email address or phone number). In this sample code, the OTP verification will be sent by email to "email@company.com".

Note that signin is not complete without the user verification step below.

NodeJSPythonGoJavaRuby

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    deliveryMethod: Delivery method to use to send OTP. Supported values include "email" or "sms"
const deliveryMethod = "email"
//    loginOptions (LoginOptions): this allows you to configure behavior during the authentication process.
const loginOptions = {
      "stepup": false,
      "mfa": false,
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }
//    refreshToken (optional): the user's current refresh token in the event of stepup/mfa

const resp = await descopeClient.otp.signIn[deliveryMethod](loginId, loginOptions);
if (!resp.ok) {
  console.log("Failed to initialize signin flow")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully initialized signin flow")
}

# Args:
#   login_id: email or phone - login_id for the user, also used for delivery
login_id = "email@company.com"
#   delivery_method: Method used to deliver the OTP. Supported delivery methods - DeliveryMethod.SMS or DeliveryMethod.EMAIL
delivery_method = DeliveryMethod.EMAIL
#   login_options (LoginOptions): this allows you to configure behavior during the authentication process.
login_options = {
      "stepup": false,
      "mfa": false,
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }
#   refresh_token (optional): the user's current refresh token in the event of stepup/mfa

try:
  descope_client.otp.sign_in(method=delivery_method, login_id=login_id, login_options=login_options)
  print ("Successfully initialized signin flow")
except AuthException as error:
  print ("Failed to initialize signin flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    deliveryMethod: Delivery method to use to send OTP. Supported values include descope.MethodEmail or descope.MethodSMS
deliveryMethod := descope.MethodEmail
//    loginID: email or phone - the loginId for the user
loginID := "email@company.com"
//    r: HttpRequest for the update call. This request should contain refresh token for the authenticated user. This can also be nil
//    loginOptions: this allows you to configure behavior during the authentication process.
loginOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

res, err := descopeClient.Auth.OTP().SignIn(ctx, deliveryMethod, loginID, nil, loginOptions)
if (err != nil){
  fmt.Println("Failed to initialize signin flow: ", err)
} else {
  fmt.Println("Successfully initialized signin flow", res)
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();
var loginOptions = LoginOptions.builder()
				.stepUp(true)
        .mfa(true)
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

OTPService otps = descopeClient.getAuthenticationServices().getOtpService();
try {
  String maskedAddress = otps.signIn(DeliveryMethod.EMAIL, loginId, loginOptions);

} catch (DescopeException de) {
  // Handle the error
}

# Sign in (log in) an existing user with the unique login_id you provide.
# The login_id field is used to identify the user. It can be an email address or a phone number.
# Provide the DeliveryMethod required for this user. If the login_id value cannot be used for the
# DeliverMethod selected (for example, 'login_id = 4567qq445km' and 'DeliveryMethod = email')
email = 'desmond@descope.com'
user = {'name': 'Desmond Copeland', 'phone': '+15555555555', 'email': email}
masked_address = descope_client.otp_sign_in(method: Descope::Mixins::Common::DeliveryMethod::EMAIL

, login_id: 'someone@example.com')

User Sign-Up or Sign-In

For signing up a new user or signing in an existing user, you can utilize the signUpOrIn functionality. Only user loginId is necessary for this function. In this sample code, the OTP verification will be sent by email to "email@company.com". To change the delivery method to send the OTP verification as a Text Message (SMS), you would change the delivery_method to sms within the below example.

Note that signUpOrIn is not complete without the user verification step below.

NodeJSPythonGoJavaRuby

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    deliveryMethod: Delivery method to use to send OTP. Supported values include "email" or "sms"
const deliveryMethod = "email"
//    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
const signUpOptions = {
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }

const resp = await descopeClient.otp.signUpOrIn[deliveryMethod](loginId, signUpOptions);
if (!resp.ok) {
  console.log("Failed to initialize signUpOrIn flow")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully initialized signUpOrIn flow")
}

# Args:
#   login_id: email or phone - login_id for the user, also used for delivery
login_id = "email@company.com"
#   delivery_method: Method used to deliver the OTP. Supported delivery methods - DeliveryMethod.SMS or DeliveryMethod.EMAIL
delivery_method = DeliveryMethod.EMAIL
#   signup_options (SignUpOptions): this allows you to configure behavior during the authentication process.
signup_options = {
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }

try:
  descope_client.otp.sign_up_or_in(method=delivery_method, login_id=login_id, signup_options=signup_options)
  print ("Successfully initialized signup or in flow")
except AuthException as error:
  print ("Failed to initialize signup or in flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    deliveryMethod: Delivery method to use to send OTP. Supported values include descope.MethodEmail or descope.MethodSMS
deliveryMethod := descope.MethodEmail
//    loginID: email or phone - the loginId for the user
loginID := "email@company.com"
//    signUpOptions: this allows you to configure behavior during the authentication process.
signUpOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

err := descopeClient.Auth.OTP().SignUpOrIn(ctx, deliveryMethod, loginID, signUpOptions)
if (err != nil){
  fmt.Println("Failed to initialize signup or in flow: ", err)
} else {
  fmt.Println("Successfully initialized signup or in flow")
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
var signUpOptions = SignupOptions.builder()
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

OTPService otps = descopeClient.getAuthenticationServices().getOtpService();
try {
  String maskedAddress = otps.signUpOrIn(DeliveryMethod.EMAIL, loginId, signUpOptions);
} catch (DescopeException de) {
  // Handle the error
}

#  Sign_up_or_in lets you handle both sign up and sign in with a single call.
#  The login_id field is used to identify the user. It can be an email address or a phone number.
#  Sign-up_or_in will first determine if login_id is a new or existing end user.
#  If login_id is new, a new end user user will be created and then authenticated using the OTP DeliveryMethod (either email, sms, or voice) specified.
#  If login_id exists, the end user will be authenticated using the OTP DeliveryMethod specified.

masked_method = descope_client.otp_sign_up_or_in(method: Descope::Mixins::Common::DeliveryMethod::SMS

, login_id: phone)

User Verification

The next step in authenticating the user is to verify the code entered by the user, using OTP verify code function. The function will return all the necessary JWT tokens, claims and user information. You can use the JWT tokens for session validation in your application middleware or app server for every route needs an authenticated user.

NodeJSPythonGoJavaRuby

// Args:
//   loginId (str): The loginId of the user being validated
const loginId = "email@company.com"
//   code (str): The authorization code enter by the end user during signup/signin
const code = "xxxxxx"
//   deliveryMethod: Delivery method to use to send OTP. Supported values include "email" or "sms"
const deliveryMethod = "email"

const resp = await descopeClient.otp.verify[deliveryMethod](loginId, code);
if (!resp.ok) {
  console.log("Failed to verify OTP code")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully verified OTP ")
  console.log(resp.data)
}

# Args:
#   login_id (str): The login_id of the user being validated
login_id = "email@company.com"
#   code (str): The authorization code enter by the end user during signup/signin
code = "xxxxxx"
#   delivery_method: Method used to deliver the OTP. Supported delivery methods - DeliveryMethod.SMS or DeliveryMethod.EMAIL
delivery_method = DeliveryMethod.EMAIL

try:
  jwt_response = descope_client.otp.verify_code(method=delivery_method, login_id=login_id, code=code)
  print ("Successfully verified user")
  print(json.dumps(jwt_response, indent=4))
except AuthException as error:
  print ("Failed to verify user")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//   deliveryMethod: Method used to deliver the OTP. Supported delivery methods - descope.MethodEmail or descope.MethodSMS
deliveryMethod := descope.MethodSMS
//   loginID: email or phone - unique ID for the user
loginID := "email@company.com"
//   code (string): The authorization code enter by the end user during sign-up/sign-in
code := "xxxxxx"
//   w: ResponseWriter to update with correct session details. You can return this to your client for setting the cookies which are used for session validation. This code should go into your application server route handling the verification of code.

authInfo, err := descopeClient.Auth.OTP().VerifyCode(ctx, method, loginID, code, w)
if (err != nil){
  fmt.Println("Failed to verify user: ", err)
} else {
  fmt.Println("Successfully verified user", authInfo)
}

// Will throw DescopeException if there is an error with update
OTPService otps = descopeClient.getAuthenticationServices().getOtpService();

try {
  AuthenticationInfo info = otps.verifyCode(DeliveryMethod.EMAIL, loginId, code);
} catch (DescopeException de) {
  // Handle the error
}

#The requested_method can be either email, sms, or voice.
#Login_id is the user's login id and value is the verification code.
#jwt_response = descope_client.otp_verify_code( method: Descope::Mixins::Common::DeliveryMethod::EMAIL SMS or VOICE, login_id: 'someone@example.com', code: '123456')

jwt_response = descope_client.otp_verify_code(method: Descope::Mixins::Common::DeliveryMethod::EMAIL, login_id: login_id, code: value)

Update Email

This function allows you to update the user's email address via email. This requires a valid refresh token. Once the user has received the OTP Code, you will need to host a page to verify the OTP code using the OTP Verify Function.

NodeJSPythonGoJavaRuby

// Args:
//   loginId (str): The loginId of the user being updated
const loginId = "email@company.com"
//   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
const email = "newEmail@company.com"
//   refreshToken (str): The session's refresh token (used for verification)
const refreshToken = "xxxxx"
//    updateOptions (UpdateOptions): this allows you to configure behavior during the authentication process.
const updateOptions = {
      "addToLoginIDs": true,
      "onMergeUseExisting": true,
      "templateOptions": {"option": "Value1"}
    }

const resp = await descopeClient.otp.update.email(loginId, email, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start OTP email update")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully started OTP email update")
  console.log(resp.data)
}

# Args:
#   login_id (str): The login_id of the user being updated
login_id = "email@company.com"
#   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
email = "newEmail@company.com"
#   refresh_token (str): The session's refresh token (used for verification)
refresh_token = "xxxxx"
#   add_to_login_ids (boolean): if true, the email will be appended to the login ID array.
add_to_login_ids = True
#   on_merge_use_existing (boolean): if true, on merge, the existing user's information (roles, tenants, etc) will be retained
on_merge_use_existing = True
#   template_options (dict): email template options
template_options = {"option": "Value1"}

try:
    jwt_response = descope_client.otp.update_user_email(login_id=login_id, email=email, refresh_token=refresh_token, add_to_login_ids=add_to_login_ids, on_merge_use_existing=on_merge_use_existing, template_options=template_options)
    print ("Successfully started OTP email update")
    print(json.dumps(jwt_response, indent=4))
except AuthException as error:
    print ("Failed to start OTP email update")
    print ("Status Code: " + str(error.status_code))
    print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//   loginId (str): The loginId of the user being updated
loginID := "email@company.com"
//   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
email := "newEmail@company.com"
//   updateOptions (&descope.UpdateOptions): this allows you to configure behavior during the authentication process.
updateOptions := &descope.UpdateOptions{}
updateOptions.AddToLoginIDs = false
updateOptions.OnMergeUseExisting = false
updateOptions.TemplateOptions = map[string]any{"option": "Value1"}
//   request (*http.Request): Request is needed to obtain JWT and send it to Descope, for verificatio


res, err := descopeClient.Auth.OTP().UpdateUserEmail(ctx, loginID, email, updateOptions, request)
if (err != nil){
  fmt.Println("Failed to start OTP email update: ", err)
} else {
  fmt.Println("Successfully started OTP email update", res)
}

// Will throw DescopeException if there is an error with update
OTPService otps = descopeClient.getAuthenticationServices().getOtpService();

try {
  AuthenticationInfo info = otps.updateUserEmail(loginId, email, refreshToken, UpdateOptions);
} catch (DescopeException de) {
  // Handle the error
}

descope_client.otp_update_user_email(method: ?, login_id: login_id, email: user_email)

Update Phone

This function allows you to update the user's phone number address via SMS. This requires a valid refresh token. Once the user has received the OTP Code, you will need to host a page to verify the OTP code using the OTP Verify Function.

NodeJSPythonGoJavaRuby

// Args:
//   deliveryMethod: Delivery method to use to send OTP.
const deliveryMethod = "sms"
//   loginId (str): The loginId of the user being updated
const loginId = "phone@company.com"
//   phone (str): The new phone number. If a phone number already exists for this end user, it will be overwritten
const phone = "+12223334455"
//   refreshToken (str): The session's refresh token (used for verification)
const refreshToken = "xxxxx"
//    updateOptions (UpdateOptions): this allows you to configure behavior during the authentication process.
const updateOptions = {
      "addToLoginIDs": true,
      "onMergeUseExisting": true,
      "templateOptions": {"option": "Value1"}
    }

const resp = await descopeClient.otp.update.phone(deliveryMethod, loginId, phone, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start OTP phone update")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully started OTP phone update")
  console.log(resp.data)
}

# Args:
#   delivery_method: Method used to deliver the OTP.
delivery_method = DeliveryMethod.SMS
#   login_id (str): The login_id of the user being updated
login_id = "phone@company.com"
#   phone (str): The new phone number. If a phone number already exists for this end user, it will be overwritten
phone = "+12223334455"
#   refresh_token (str): The session's refresh token (used for verification)
refresh_token = "xxxxx"
#   add_to_login_ids (boolean): if true, the phone will be appended to the login ID array.
add_to_login_ids = True
#   on_merge_use_existing (boolean): if true, on merge, the existing user's information (roles, tenants, etc) will be retained
on_merge_use_existing = True
#   template_options (dict): email template options
template_options = {"option": "Value1"}

try:
    jwt_response = descope_client.otp.update_user_phone(delivery_method=delivery_method, login_id=login_id, phone=phone, refresh_token=refresh_token, add_to_login_ids=add_to_login_ids, on_merge_use_existing=on_merge_use_existing, template_options=template_options)
    print ("Successfully started OTP phone update")
    print(json.dumps(jwt_response, indent=4))
except AuthException as error:
    print ("Failed to start OTP phone update")
    print ("Status Code: " + str(error.status_code))
    print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//   deliveryMethod: Method used to deliver the OTP.
deliveryMethod := descope.MethodSMS
//   loginId (str): The loginId of the user being updated
loginID := "phone@company.com"
//   phone (str): The new phone number. If a phone number already exists for this end user, it will be overwritten
phone := "+12223334455"
//   updateOptions (&descope.UpdateOptions): this allows you to configure behavior during the authentication process.
updateOptions := &descope.UpdateOptions{}
updateOptions.AddToLoginIDs = false
updateOptions.OnMergeUseExisting = false
updateOptions.TemplateOptions = map[string]any{"option": "Value1"}
//   request (*http.Request): Request is needed to obtain JWT and send it to Descope, for verificatio


res, err := descopeClient.Auth.OTP().UpdateUserPhone(ctx, deliveryMethod, loginID, phone, updateOptions, request)
if (err != nil){
  fmt.Println("Failed to start OTP phone update: ", err)
} else {
  fmt.Println("Successfully started OTP phone update", res)
}

// Will throw DescopeException if there is an error with update
OTPService otps = descopeClient.getAuthenticationServices().getOtpService();

try {
  AuthenticationInfo info = otps.updateUserPhone(deliveryMethod, loginId, phone, refreshToken, UpdateOptions);
} catch (DescopeException de) {
  // Handle the error
}

descope_client.otp_update_user_phone(method: ?, login_id: login_id, phone: user_phone)

Session Validation

The final step of completing the authentication with Descope is to validate the user session. Descope provides rich session management capabilities, including configurable session timeouts and logout functions. You can find the details and sample code for backend session validation here.

Checkpoint: Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Application is working Need Help?

Was this article helpful?Yes No