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.
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.
Alert
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
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
baseUrl: Custom domain that must be configured to manage token response in cookies. This makes sure every request to our service is through your custom domain, preventing accidental domain blockages.
baseStaticUrl: Custom domain to override the base URL that is used to fetch static files.
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.
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.
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.
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.
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.
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.
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.