Magic Link

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 magic link is a single-use link sent to the user for authentication (sign-up or sign-in) that validates their identity. The Descope service can send magic links via email or SMS texts.

The browser tab that is opened after clicking the magic link gets the authenticated session cookies. For example, consider a user that starts the login process on a laptop browser and gets a magic link delivered to their email inbox. When they click the email link, a new browser tab will open and they will be logged in on the new tab.

alt="This image shows the magic link flow within Descope for client SDK."

Consider using magic links when your users typically use only one device to access your application, and when opening new tabs is not a big inconvenience.

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

ReactNextJSNextAuthWebJSVue.jsHTMLAngular

npm i --save @descope/react-sdk

npm i --save @descope/next-sdk

npm i --save next-auth

npm i --save @descope/web-js-sdk

npm i --save @descope/vue-sdk

<!-- Not applicable for HTML -->

npm i --save @descope/angular-sdk

Import and initialize SDK

ReactNextJSNextAuthWebJSVue.jsHTMLAngular

import { AuthProvider } from '@descope/react-sdk'
import { Descope, useDescope } from '@descope/react-sdk'

const AppRoot = () => {
	return (
		<AuthProvider
			projectId="__ProjectID__"
			// If the Descope project manages the token response in cookies,
            // a custom domain must be configured
            // (e.g., https://auth.app.example.com)
			// and should be set as the baseUrl property.
			// baseUrl = "https://auth.app.example.com"
		>
			<App />
		</AuthProvider>
	);
};

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<AuthProvider projectId="__ProjectID__">
			<html lang="en">
				<body>{children}</body>
			</html>
		</AuthProvider>
	);
}

// app/api/auth/[...nextauth]
import { NextAuthOptions } from "next-auth"
import NextAuth from "next-auth/next";

export const authOptions: NextAuthOptions = {
  providers: [
    {
      id: "descope",
      name: "Descope",
      type: "oauth",
      wellKnown: `https://api.descope.com/${process.env.DESCOPE_PROJECT_ID}/.well-known/openid-configuration`,
      authorization: { params: { scope: "openid email profile" } },
      idToken: true,
      clientId: process.env.DESCOPE_PROJECT_ID,
      clientSecret: process.env.DESCOPE_ACCESS_KEY,
      checks: ["pkce", "state"],
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
          image: profile.picture,
        }
      },
    },
  ], 
  callbacks: {
    async jwt({token, account, profile}) {
      if (account) {
        return {
          ...token,
          access_token: account.access_token,
          expires_at: Math.floor(Date.now() / 1000 + account.expires_in),
          refresh_token: account.refresh_token,
          profile: {
            name: profile?.name,
            email: profile?.email,
            image: profile?.picture,
            },
          }
        } else if (Date.now() < token.expires_at * 1000) {
          return token
        } else {
          try {
            const response = await fetch("https://api.descope.com/oauth2/v1/token", {
              headers: {"Content-Type": "application/x-www-form-urlencoded"},
              body: new URLSearchParams({
                client_id: "__ProjectID__",
                client_secret: "<Descope Access Key>",
                grant_type: "refresh_token",
                refresh_token: token.refresh_token,
              }),
              method: "POST",
            })
            
            const tokens = await response.json()
            
            if (!response.ok) throw tokens
            
            return {
              ...token,
              access_token: tokens.access_token,
              expires_at: Math.floor(Date.now() / 1000 + tokens.expires_in),
              refresh_token: tokens.refresh_token ?? token.refresh_token,
            }
          } catch (error) {
            console.error("Error refreshing access token", error)
            return {...token, error: "RefreshAccessTokenError"}
            }
          }
        },
    
        async session({session, token}) {
          if (token.profile) {
            session.user = token.profile;
          }
    
          session.error = token.error
          session.accessToken = token.access_token
          return session
        },
    }
}

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

// app/provider.tsx
'use client'

import { SessionProvider } from "next-auth/react"


export default function NextAuthSessionProvider(
    { children }:
    { children: React.ReactNode }
) {
    return (
        <SessionProvider>
            { children }
        </SessionProvider>
    )
}

// app/layout.tsx
import NextAuthSessionProvider from './provider'


export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NextAuthSessionProvider>
          <div>
            {children}
          </div>
        </NextAuthSessionProvider>
      </body>
    </html>
  )
}

import DescopeSdk from '@descope/web-js-sdk';
try {
    //  baseUrl="<URL>" // you can also configure the baseUrl ex: https://auth.company.com - this is useful when you utilize CNAME within your Descope project.
    const descopeSdk = DescopeSdk({ projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

import { createApp } from "vue";
import App from "@/App.vue";
import descope, { getSdk } from "@descope/vue-sdk";

const app = createApp(App);
app.use(router);

app.use(descope, {
  projectId: '__Project_ID__',
  baseUrl: "<base url>", // Optional
});

const sdk = getSdk();
sdk?.onSessionTokenChange((newSession) => {
  // here you can implement custom logic when the session is changing
});

<head>
    <script src="https://unpkg.com/@descope/web-js-sdk@x.x.x/dist/index.umd.js"></script>
    <!-- Please replace `x.x.x` with the latest version of the WebJS SDK, which you can get from [here](https://www.npmjs.com/package/@descope/web-js-sdk) -->
</head>

// app.module.ts
import { NgModule, APP_INITIALIZER} from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { DescopeAuthModule, DescopeAuthService, descopeInterceptor } from '@descope/angular-sdk';
import { AppComponent } from './app.component';
import {
	HttpClientModule,
	provideHttpClient,
	withInterceptors
} from '@angular/common/http';
import { zip } from 'rxjs';

export function initializeApp(authService: DescopeAuthService) {
	return () => zip([authService.refreshSession(), authService.refreshUser()]);
}

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    DescopeAuthModule.forRoot({
      projectId: 'YOUR_PROJECT_ID'
    })
  ],
  providers: [
    {
        provide: APP_INITIALIZER,
        useFactory: initializeApp,
        deps: [DescopeAuthService],
        multi: true
      },
      provideHttpClient(withInterceptors([descopeInterceptor]))
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

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 magic-link will be sent by email to "email@company.com". To change the delivery method to send the magic-link as a text, you would change the deliveryMethod to sms within the below example.

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

ReactWebJSHTML

// 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"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk = useDescope();
const resp = await descopeSdk.magicLink.signUp[deliveryMethod](loginId, uri, 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.
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"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk.magicLink.signUp[deliveryMethod](loginId, uri, 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")
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function magicLinkSignUp(method) {
    // Args:
    //    user: Optional user object to populate new user information.
    const user = {
      "name": document.getElementById("name").value,
      "phone": document.getElementById("phone").value,
      "email": document.getElementById("email").value
    }
    //    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
    const loginId = document.getElementById("email").value
    //    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
    const uri = "http://auth.company.com/api/verify_magiclink"
    //    deliveryMethod: Delivery method to use to send magic link. Supported values include "email" or "sms"
    const deliveryMethod = method
    //    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
    const signUpOptions = {
          "customClaims": {"claim": "Value1"},
          "templateOptions": {"option": "Value1"}
        }

    const resp = await descopeSdk.magicLink.signUp[deliveryMethod](loginId, uri, user, signUpOptions);
    if (!resp.ok) {
      window.alert("Failed to initialize signup flow\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully initialized signup flow")
      window.alert("Successfully initialized Magic Link Flow, please close this window and go to your email or phone and click the link to log in.")
    }
  }
</script>

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 magic-link will be sent by email to "email@company.com".

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

ReactWebJSHTML

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk = useDescope();
const resp = await descopeSdk.magicLink.signIn[deliveryMethod](loginId, uri, 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:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk.magicLink.signIn[deliveryMethod](loginId, uri, 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")
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function magicLinkSignIn(method) {
    // Args:
    //    loginId: email or phone for the user
    const loginId = document.getElementById("loginId").value
    //    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
    const uri = "http://auth.company.com/api/verify_magiclink"
    //    deliveryMethod: Delivery method to use to send magic link. Supported values include "email" or "sms"
    const deliveryMethod = method
    //    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 descopeSdk.magicLink.signIn[deliveryMethod](loginId, uri, loginOptions);
    if (!resp.ok) {
      window.alert("Failed to initialize signin flow\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully initialized signin flow")
      window.alert("Successfully initialized Magic Link Flow, please close this window and go to your email or phone and click the link to log in.")
    }
  }
</script>

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 magic-link will be sent by email to "email@company.com". To change the delivery method to send the magic-link as a text, you would change the deliveryMethod to sms within the below example.

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

ReactWebJSHTML

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk = useDescope();
const resp = await descopeSdk.magicLink.signUpOrIn[deliveryMethod](loginId, uri, 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:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
const loginId = "email@company.com"
//    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
const uri = "http://auth.company.com/api/verify_magiclink"
//    deliveryMethod: Delivery method to use to send magic-link. 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 descopeSdk.magicLink.signUpOrIn[deliveryMethod](loginId, uri, 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")
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });

  async function magicLinkSignUpOrIn(method) {
    // Args:
    //    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
    const loginId = document.getElementById("email").value
    //    uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'
    const uri = "http://auth.company.com/api/verify_magiclink"
    //    deliveryMethod: Delivery method to use to send magic link. Supported values include "email" or "sms"
    const deliveryMethod = method
    //    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
    const signUpOptions = {
          "customClaims": {"claim": "Value1"},
          "templateOptions": {"option": "Value1"}
        }

    const resp = await descopeSdk.magicLink.signUpOrIn[deliveryMethod](loginId, uri, signUpOptions);
    if (!resp.ok) {
      window.alert("Failed to initialize signup or in flow\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully initialized signup or in flow")
      window.alert("Successfully initialized Magic Link Flow, please close this window and go to your email or phone and click the link to log in.")
    }
  }
</script>

User Verification

Once a user clicks the magic-link, your application must call the verify function. This means that this function needs to be called from your application when the user clicks the magiclink. The function call will return all the the necessary JWT tokens and claims and user information in the resp dictionary. The sessionJwt within the resp is needed for session validation.

ReactWebJSHTML

// Args:
//  token:  URL parameter containing the magic link token for example, http://auth.company.com/api/verify_magiclink?t=token.
const token = "xxxx"

const descopeSdk = useDescope();
const resp = await descopeSdk.magicLink.verify(token)
if (!resp.ok) {
  console.log("Failed to verify magic link token")
  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 magic link token")
}

// Args:
//  token:  URL parameter containing the magic link token for example, http://auth.company.com/api/verify_magiclink?t=token.
const token = "xxxx"

const resp = await descopeSdk.magicLink.verify(token)
if (!resp.ok) {
  console.log("Failed to verify magic link token")
  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 magic link token")
}

<script>
  magicLinkVerify(tokenFromURL)

  async function magicLinkVerify(thisToken) {
    // Args:
    //  token:  URL parameter containing the magic link token for example, http://auth.company.com/api/verify_magiclink?t=token.
    const token = thisToken

    const resp = await descopeSdk.magicLink.verify(token);
    if (!resp.ok) {
      window.alert("Failed to verify Magic Link Token\nStatus Code: " + resp.code
        + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
      console.log("Successfully verified Magic Link Token")
      window.location.replace("../loggedIn?userId=" + encodeURIComponent(resp.data.user.loginIds) + "&sessionJwt=" + resp.data.sessionJwt)
    }
  }
</script>

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 magic link Code, you will need to host a page to verify the magic link code using the magic link Verify Function.

ReactWebJSHTML

// 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 descopeSdk = useDescope();
const resp = await descopeSdk.magicLink.update.email(loginId, email, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start magic link 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 magic link email update")
  console.log(resp.data)
}

// 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 descopeSdk.magicLink.update.email(loginId, email, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start magic link 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 magic link email update")
  console.log(resp.data)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });


  async function magicLinkUpdateEmail() {
    // 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 descopeSdk.magicLink.update.email(loginId, email, refreshToken, updateOptions);
    if (!resp.ok) {
        window.alert("Failed to start magic link email update\nStatus Code: " + resp.code
            + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
        console.log("Successfully started magic link email update")
        console.log(resp.data.sessionJwt)
        window.alert("Successfully initialized Magic Link Flow, please close this window and go to your email or phone and click the link to log in.")
    }
  }
</script>

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 magic link Code, you will need to host a page to verify the magic link code using the magic link Verify Function.

ReactWebJSHTML

// Args:
//   deliveryMethod: Delivery method to use to send magic link.
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 descopeSdk = useDescope();
const resp = await useDescope.magicLink.update.phone(deliveryMethod, loginId, phone, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start magic link 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 magic link phone update")
  console.log(resp.data)
}

// Args:
//   deliveryMethod: Delivery method to use to send magic link.
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 useDescope.magicLink.update.phone(deliveryMethod, loginId, phone, refreshToken, updateOptions);
if (!resp.ok) {
  console.log("Failed to start magic link 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 magic link phone update")
  console.log(resp.data)
}

<script>
  let descopeSdk = Descope({projectId: '__ProjectID__', persistTokens: true, autoRefresh: true });


  async function magicLinkUpdateEmail() {
    // Args:
    //   deliveryMethod: Delivery method to use to send magic link.
    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 useDescope.magicLink.update.phone(deliveryMethod, loginId, phone, refreshToken, updateOptions);
    if (!resp.ok) {
        window.alert("Failed to start magic link phone update"\nStatus Code: " + resp.code
            + "\nError Code: " + resp.error.errorCode + "\nError Description: " + resp.error.errorDescription + "\nError Message: " + resp.error.errorMessage)
    }
    else {
        console.log("Successfully started magic link phone update")
        console.log(resp.data.sessionJwt)
        window.alert("Successfully initialized Magic Link Flow, please close this window and go to your email or phone and click the link to log in.")
    }
  }
</script>

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 client 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