Enchanted Link via Backend SDKs

This guide is meant for developers that are NOT using Descope on the frontend to design login screens and authentication methods.

If you'd like to use Descope Flows, Quick Start should be your starting point. If you'd like to use our Client SDKs, refer to our Client SDK docs.

An enchanted link is a single-use link sent to the user for authentication (sign-up or sign-in) that validates their identity. The Descope service sends enchanted links via email.

Enchanted links are an enhanced version of magic links. Enchanted links enable users to start the login process on one device (the originating device) while clicking the enchanted link on a different device. When the user clicks the correct link, their session on the originating device is validated, and they are logged in. A special security feature of enchanted link is that the end-user needs to pick the correct link from the three links delivered to them.

Note

Enchanted links are user friendly since the user does not have to switch tabs or applications to log in. The browser tab they initiated login from is the only tab they need to use.

Use Cases

New user signup: The following actions must be completed, first User Sign-Up, then within the same route begin Polling for a valid session, and when the enchanted link is clicked User Verification
Existing user signin: The following actions must be completed, first User Sign-In, then within the same route begin Polling for a valid session, and when the enchanted link is clicked 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 within the same route begin Polling for a valid session, and when the enchanted link is clicked User Verification

Backend SDK

Install SDK

Terminal

npm i --save @descope/node-sdk

Import and initialize SDK

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

To register a new user, you can use the SignUp function. In the example below, an Enchanted Link is sent to email@company.com.

The SignUp call returns two important values:

pendingRef — used by your application to poll the verification status on the originating device.
linkId — should be shown to the user in your application so they can identify and click the correct link in the email they receive.

Make sure your application uses the pendingRef to check when the user has successfully verified their sign-up.

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

// Args:
//    user: user meta data for signup.
const user = {"name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}
//    loginId: email - 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_enchantedlink"
//    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
const signUpOptions = {
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }
 
const resp = await descopeClient.enchantedLink.signUp(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")
  const linkId = resp.data.linkId;
  console.log("linkId " + linkId)
  const pendingRef = resp.data.pendingRef;
  console.log("pendingRef " + pendingRef)
}

To login an existing user, you can use the SignIn function. In this example, an Enchanted Link is sent to email@company.com. The signIn call returns two key values:

pendingRef — used by your application to poll the verification status on the originating device.
linkId — should be displayed to the user so they can identify and click the correct link in the email they receive.

Your application should then use the pendingRef to monitor when the user completes verification.

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

// Args:
//    loginId: email - 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_enchantedlink"
//    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.enchantedLink.signIn(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")
  const linkId = resp.data.linkId;
  console.log("linkId " + linkId)
  const pendingRef = resp.data.pendingRef;
  console.log("pendingRef " + pendingRef)
}

To sign up a new user or sign in an existing user, you can use the signUpOrIn function. In the example below, an Enchanted Link is sent to email@company.com.

The signUpOrIn call returns two important values:

pendingRef — used by your application to poll the verification status on the originating device.
linkId — should be shown to the user in your application so they can identify and click the correct link in the email they receive.

Make sure your application uses the pendingRef to check when the user has successfully verified their sign-in or sign-up.

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

// Args:
//    loginId: email - 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_enchantedlink"
//    signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.
const signUpOptions = {
      "customClaims": {"claim": "Value1"},
      "templateOptions": {"option": "Value1"}
    }
 
const resp = await descopeClient.enchantedLink.signUpOrIn(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")
  const linkId = resp.data.linkId;
  console.log("linkId " + linkId)
  const pendingRef = resp.data.pendingRef;
  console.log("pendingRef " + pendingRef)
}

User Verification

Call the verify function from your verify url. This means that this function needs to be called when the user clicks the enchanted link. If the token is valid, the user will be authenticated and session returned to the polling thread (see next step).

// Args:
//  token:  URL parameter containing the enchanted link token for example, https://auth.company.com/api/verify_enchantedlink?t=token.
const token = "xxxx"
 
const resp = await mydescopeClient.enchantedLink.verify(token);
if (!resp.ok) {
  console.log("Failed to verify enchanted link")
  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 enchanted link")
}

Polling for valid session

On the route where you initialized the signIn, signUp, or signUpOrIn, you need to repeatedly poll for a valid session. get_session(token) is called repeatedly until the user clicks the enchanted link URL they received, so that the session on the initiating device can be directed to your desired page.

// Args:
//    pendingRef: Reference token received from signup or signin call.
const pendingRef = "xxxxx"
 
const resp = await descopeClient.enchantedLink.waitForSession(pendingRef);
if (!resp.ok) {
  console.log("Failed to complete polling 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 completed polling flow")
  console.log(resp)
}

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

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

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.

Need help?

Was this helpful?

Checkpoint

On this page