@descope/node-sdk

Descope Node.js SDK

Use the Descope NodeJS SDK for NodeJS/Express to quickly and easily add user authentication to your application or website. If you need more background on how the ExpresSDKs work, click here.

ExpressStart with OTP Authentication

This section will show you how to implement user authentication using a one-time password (OTP). A typical four step flow for OTP authentictaion is shown below.

flowchart LR
  signup[1. customer sign-up]-- customer gets OTP -->verify[3. customer verification]
  signin[2. customer sign-in]-- customer gets OTP -->verify
  verify-- access private API -->validate[4. session validation]

Prerequisites

Replace any instance of <ProjectID> in the code below with your company's Project ID, which can be found in the Descope console.

• Run the following commands in your project

  These commands will add the Descope NodeJS SDK as a project dependency.

  npm i --save @descope/node-sdk
  

• Import and initialize the ExpresSDK for NodeJS client in your source code

  import DescopeClient from '@descope/node-sdk'
  
  descopeClient, err := DescopeClient({ projectId: <ProjectID> })
  

1. Customer Sign-up

In your sign-up route for OTP (for example, myapp.com/signup) generate a sign-up request and send the OTP verification code via the selected delivery method. In the example below an email is sent to "[e-mail]". In additon, optional user data (for exmaple, a custom username in the code sample below) can be gathered during the sign-up process.

await clientAuth.auth.otp.signUp.email("[e-mail]")

2. Customer Sign-in

In your sign-in route for OTP (for exmaple, myapp.com/login) generate a sign-in request send the OTP verification code via the selected delivery method. In the example below an email is sent to "[e-mail]".

await clientAuth.auth.otp.signIn.email("[e-mail]")

3. Customer Verification

In your verify customer route for OTP (for example, myapp.com/verify) verify the OTP from either a customer sign-up or sign-in. The VerifyCode function call will write the necessary tokens and cookies to the response writer (w), which will be used by the NodeJS client to validate each session interaction.

const out = await clientAuth.auth.otp.verify.email(identifier, code)
if (out.data.cookies) {
    res.set('Set-Cookie', out.data.cookies)
}

4. Session Validation

Session validation checks to see that the visitor to your website or application is who they say they are, by comparing the value in the validation variables against the session data that is already stored.

const out = await clientAuth.auth.validateSession(session_jwt, refresh_jwt)
if (out?.cookies) {
    res.set('Set-Cookie', out.cookies)
}

ExpressStart with MagicLink Authentication

This section will help you implement user authentication using Magiclinks. A typical four step flow for OTP authentictaion is shown below.

flowchart LR
  signup[1. customer sign-up]-- customer gets MagicLink -->verify[3. MagicLink verification]
  signin[2. customer sign-in]-- customer gets MagicLink -->verify
  verify-- access private API -->validate[4. session validation]

Prerequisites

Replace any instance of <ProjectID> in the code below with your company's Project ID, which can be found in the Descope console.

• Run the following commands in your project

  These commands will add the Descope NodeJS SDK as a project dependency.

  npm i --save @descope/node-sdk
  

• Import and initialize the ExpresSDK for NodeJS client in your source code

  import DescopeClient from '@descope/node-sdk'
  
  descopeClient, err := DescopeClient({ projectId: <ProjectID> })
  

1. Customer Sign-up

In your sign-up route using magic link (for example, myapp.com/signup) generate a sign-up request and send the magic link via the selected delivery method. In the example below an email is sent to "[e-mail]" containing the magic link and the link will automatically return back to the provided URL ("https://mydomain.com/verify"). In additon, optional user data (for exmaple, a custom username in the code sample below) can be gathered during the sign-up process.

await clientAuth.auth.magiclink.signUp.email("[e-mail]", { name: "custom name" })

2. Customer Sign-in

In your sign-in route using magic link (for exmaple, myapp.com/login) generate a sign-in request send the magic link via the selected delivery method. In the example below an email is sent to "[e-mail]" containing the magic link and the link will automatically return back to the provided URL ("https://mydomain.com/verify").

await clientAuth.auth.magiclink.signIn.email("[e-mail]")

3. Customer Verification

In your verify customer route for magic link (for example, mydomain.com/verify) verify the token from either a customer sign-up or sign-in. The VerifyMagicLink function call will write the necessary tokens and cookies to the response writer (w), which will be used by the Go client to validate each session interaction.

const out = await clientAuth.auth.magiclink.verify(token)
if (out.data.cookies) {
    res.set('Set-Cookie', out.data.cookies)
}

4. Session Validation

Session validation checks to see that the visitor to your website or application is who they say they are, by comparing the value in the validation variables against the session data that is already stored.

const out = await clientAuth.auth.validateSession(session_jwt, refresh_jwt)
if (out?.cookies) {
    res.set('Set-Cookie', out.cookies)
}

Run the Examples

TL;DR Run npm run quick

Instantly run the end-to-end ExpresSDK for Node examples, as shown below. The source code for these examples are in the folder GitHib go-sdk/examples folder.

Prerequisites

Run the following commands in your project. Replace any instance of <ProjectID> in the code below with your company's Project ID, which can be found in the Descope console.

This commands will add the Descope NodeJS SDK as a project dependency, clone the SDK repository locally, and set the DESCOPE_PROJECT_ID.

npm i --save @descope/node-sdk
git clone github.com/descope/node-sdk
export DESCOPE_PROJECT_ID=<ProjectID>

Run an example

1. Run this command in your project to build the examples.

   npm i
   npm run build
   cd examples/es6
   npm i
   npm start
   

2. Run a specific example

   npm i
   npm run build
   cd examples/commonjs
   npm i
   npm start
   

License

The Descope ExpresSDK for Go is licensed for use under the terms and conditions of the MIT license Agreement.