Magic Link via Mobile SDKs
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
User Sign-Up
For registering a new user, your application 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 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
The Descope SDK allows for you to update user's email address. With this function, you will pass the user's loginId
and the new email
address you want associated to the user. In order to verify the email address, the magic link will be sent via the email delivery
method. Once the update email function has been called, you will need to verify the token before the email address will be updated.
Update Phone
The Descope SDK allows for you to update user's phone number. With this function, you will pass the user's loginId
and the new
phone number you want associated to the user. In order to verify the phone number, the magic link will be sent via the sms delivery
method. Once the update phone function has been called, you will need to verify the token before the phone
number will be updated.
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.