descope / node-sdk

Descope SDK for Node.js The Descope SDK for Node.js provides convenient access to the Descope user management and authentication API for a backend written in Node.js. You can read more on the Descope Website. Requirements The SDK supports Node version 16 and above. Installing the SDK Install the package with: Authentication Functions Setup Before you can use authentication functions listed below, you must initialize to use all of the built-in SDK functions. You'll need your Descope to create this, and you can find it on the project page in the Descope Console. Once you've created a , you can use that to work with the following functions: • OTP Authentication • Magic Link • Enchanted Link • OAuth • SSO/SAML • TOTP Authentication • Passwords • Session Validation • Roles & Permission Validation • Logging Out Management Functions Setup Before you can use management functions listed below, you must initialize . If you wish to also use management functions, you will need to initialize a new version of your , but this time with a as well as your . Create a management key in the Descope Console. Then, you can use that to work with the following functions: • Manage Tenants • Manage Users • Manage Access Keys • Manage SSO Setting • Manage Permissions • Manage Roles • Query SSO Groups • Manage Flows • Manage JWTs • Impersonate • Embedded Links • Audit • Manage FGA (Fine-grained Authorization) • Manage Project • Manage SSO applications • Manage Management Keys • Manage Descopers If you wish to run any of our code samples and play with them, check out our Code Examples section. If you're performing end-to-end testing, check out the Utils for your end to end (e2e) tests and integration tests section. You will need to use the you created under the setup of Management Functions. Authentication Management Key The is an alternative to the that provides a way to perform management operations while maintaining separation between authentication and management clients. Key Differences • **Purpose**: Use for authentication-related management operations, while is for general management operations • **Client Separation**: You can have one client for management operations and another for authentication operations • **Mutual Exclusivity**: You cannot pass both and together - choose one based on your use case Usage Examples **Using authManagementKey for authentication operations:** **Separate clients for different operations:** **Note**: Create your authentication management key in the Descope Console, similar to how you create a regular management key. --- Error Handling Every operation may fail. In case it does, there will be information regarding what happened on the response object. A typical case of error handling might look something like: --- OTP Authentication Send a user a one-time password (OTP) using your preferred delivery method (_Email / SMS / Voice call / WhatsApp_). An email address or phone number must be provided accordingly. The user can either , or The user will receive a code using the selected delivery method. Verify that code using: The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on session validation Magic Link Send a user a Magic Link using your preferred delivery method (_email / SMS_). The Magic Link will redirect the user to page where the its token needs to be verified. This redirection can be configured in code, or globally in the Descope Console The user can either , or To verify a magic link, your redirect page must call the validation function on the token ( ) parameter ( ): The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on session validation Enchanted Link Using the Enchanted Link APIs enables users to sign in by clicking a link delivered to their email address. The email will include 3 different links, and the user will have to click the right one, based on the 2-digit number that is displayed when initiating the authentication process. This method is similar to Magic Link but differs in two major ways: • The user must choose the correct link out of the three, instead of having just one single link. • This supports cross-device clicking, meaning the user can try to log in on one device, like a computer, while clicking the link on another device, for instance a mobile phone. The Enchanted Link will redirect the user to page where the its token needs to be verified. This redirection can be configured in code per request, or set globally in the Descope Console. The user can either , or After sending the link, you must poll to receive a valid session using the from the previous step. A valid session will be returned only after the user clicks the right link. To verify an enchanted link, your redirect page must call the validation function on the token ( ) parameter ( ). Once the token is verified, the session polling will receive a valid response. The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on session validation OAuth Users can authenticate using their social logins, via the OAuth protocol. Configure your OAuth settings on the Descope console. To start an OAuth flow call: The user will authenticate with the authentication provider, and will be redirected back to the redirect URL, with an appended HTTP URL parameter. Exchange it to validate the user: The session and refresh JWTs should be returned to the caller, and passed with every request in the session. Read more on session validation SSO/SAML Users can authenticate to a specific tenant using SAML or Single Sign On. Configure your SSO/SAML settings on the Descope console. To start a flow call: The user will authenticate with the authentication provider configured for that tenant, and will be redirected back to the redirect URL, with an appended HTTP URL parameter.…