Magic Link via Client 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.
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
Use Cases
- New user signup: The following actions must be completed, first User Sign-Up then User Verification
- Existing user signin: The following actions must be completed, first User Sign-In then 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 User Verification
Client SDK
Install SDK
Import and initialize SDK
Parameters:
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.
OIDC Configuration
If you're using our SDK as an OIDC client with our Federated Apps, you can initialize the oidcConfig
parameter with the following items:
applicationId
: This is the application id, that can be found within the settings of your Federated ApplicationredirectUri
: This is the url that will be redirected to if the user is unauthenticated. The default redirect URI will be used if not provided.scope
: This is a string of the scopes that the OIDC client will request from Descope. This should be one string value with spaces in between each scope. The default scopes are:'openid email roles descope.custom_claims offline_access'
User Sign-Up
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.
User Sign-In
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.
User Sign-Up or Sign-In
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.
User Verification
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.
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 magic link Code, you will need to host a page to verify the magic link code using the magic link Verify Function.
Update Phone
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.
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 client session validation here.
Checkpoint
Your application is now integrated with Descope. Please test with sign-up or sign-in use case.