Embedded Link via Backend SDKs

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

If you'd like to use Descope Flows, Quick Start should be your starting point.

An embedded link generates a single-use token for authenticating an existing user. Once generated, the embedded link token can be sent to a user via various use cases such as email, SMS, etc, or you can use it manually similarly to a machine-to-machine implementation. Embedded link tokens are verified using the magic link verification function.

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

Generate Embedded Link

When authenticating via embedded link, you first need to generate the embedded link token. The code below shows how to generate the embedded link token.

Also note that signup 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"
//    customClaims: Additional claims to place on the jwt after verification
const customClaims = {"Key1": "Value1"}
 
const resp = await descopeClient.management.user.generateEmbeddedLink(loginId, customClaims);
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 token = resp.data.token;
  console.log("Token " + token)
}

Embedded Link Verification

Once the embedded token has been generated, you can send to a user via various use cases such as email, SMS, etc, or you can use it manually similarly to a machine-to-machine implementation. Embedded link tokens are verified using the magic link verification function. Below are examples of verifying the token utilizing the backend SDKs.

// Args:
//  token: generated embedded link token
const token = "xxxx"
 
const resp = await descopeClient.magicLink.verify(token)
if (!resp.ok) {
  console.log("Failed to verify user")
  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 user")
}

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?