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.
An enchanted link is a single-use link sent to the user for authentication (sign-up or sign-in) that
validates their identity. The Descope service sends enchanted links via email.
Enchanted links are an enhanced version of magic links. Enchanted links enable users to start the login process on one device (the originating device) while clicking the enchanted link on a different
device. When the user clicks the correct link, their session on the originating device is validated, and they are logged in. A special security feature
of enchanted link is that the end-user needs to pick the correct link from the three links delivered to them.
Alert
Enchanted links are user friendly since the user does not have to switch
tabs or applications to log in. The browser tab they initiated login from is the
only tab they need to use.
import { AuthProvider } from '@descope/react-sdk'import { Descope, useDescope } from '@descope/react-sdk'const AppRoot = () => { return ( <AuthProvider projectId="__ProjectID__" // If the Descope project manages the token response in cookies, // a custom domain must be configured // (e.g., https://auth.app.example.com) // and should be set as the baseUrl property. // baseUrl = "https://auth.app.example.com" > <App /> </AuthProvider> );};
For registering a new user, your application client should accept user information, including an email or
phone number used for verification. The application client should send this information to your application
server. In this sample code, the enchanted link will be sent by email to email@company.com.
The signup call returns a pendingRef and a linkId. Display the linkId to end user from
your application so that they can click on the correct link in the email that they receive. Then your
application will utilize the pendingRef to poll for verification status on the originating device.
Also note that signup is not complete without the user verification step below.
// Args:// user: user meta data for signup.const user = {"name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}// loginId: email - becomes the loginId for the user from here on and also used for deliveryconst loginId = "email@company.com"// uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'const uri = "http://auth.company.com/api/verify_enchantedlink"// signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.const signUpOptions = { "customClaims": {"claim": "Value1"}, "templateOptions": {"option": "Value1"} }const descopeSdk = useDescope();const resp = await descopeSdk.enchantedLink.signUp(loginId, uri, user, signUpOptions);if (!resp.ok) { console.log("Failed to initialize signup flow") console.log("Status Code: " + resp.code) console.log("Error Code: " + resp.error.errorCode) console.log("Error Description: " + resp.error.errorDescription) console.log("Error Message: " + resp.error.errorMessage)}else { console.log("Successfully initialized signup flow") const linkId = resp.data.linkId; console.log("linkId " + linkId) const pendingRef = resp.data.pendingRef; console.log("pendingRef " + pendingRef)}
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 enchanted link will be sent by email to email@company.com. The signin
call returns a pendingRef and a linkId. Display the linkId to end user from
your application so that they can click on the correct link in the email that they receive. Then your
application will utilize the pendingRef to poll for verification status on the originating device.
Also note that signin is not complete without the user verification step below.
// Args:// loginId: email - becomes the loginId for the user from here on and also used for deliveryconst loginId = "email@company.com"// uri: (Optional) this is the link that user is sent (code appended) for verification. Your application needs to host this page and extract the token for verification. The token arrives as a query parameter named 't'const uri = "http://auth.company.com/api/verify_enchantedlink"// loginOptions (LoginOptions): this allows you to configure behavior during the authentication process.const loginOptions = { "stepup": false, "mfa": false, "customClaims": {"claim": "Value1"}, "templateOptions": {"option": "Value1"} }// refreshToken (optional): the user's current refresh token in the event of stepup/mfaconst descopeSdk = useDescope();const resp = await descopeSdk.enchantedLink.signIn(loginId, uri, loginOptions);if (!resp.ok) { console.log("Failed to initialize signin flow") console.log("Status Code: " + resp.code) console.log("Error Code: " + resp.error.errorCode) console.log("Error Description: " + resp.error.errorDescription) console.log("Error Message: " + resp.error.errorMessage)}else { console.log("Successfully initialized signin flow") const linkId = resp.data.linkId; console.log("linkId " + linkId) const pendingRef = resp.data.pendingRef; console.log("pendingRef " + pendingRef)}
For signing up a new user or signing in an existing user, you can utilize the signUpOrIn functionality.
In this sample code, the enchanted link will be sent by email to email@company.com. The signin
call returns a pendingRef and a linkId. Display the linkId to end user from
your application so that they can click on the correct link in the email that they receive. Then your
application will utilize the pendingRef to poll for verification status on the originating device.
Note that signUpOrIn is not complete without the user verification step below.
// Args:// loginId: email - becomes the loginId for the user from here on and also used for deliveryconst loginId = "email@company.com"// signUpOptions (SignUpOptions): this allows you to configure behavior during the authentication process.const signUpOptions = { "customClaims": {"claim": "Value1"}, "templateOptions": {"option": "Value1"} }const descopeSdk = useDescope();const resp = await descopeSdk.enchantedLink.signUpOrIn(loginId, uri, signUpOptions);if (!resp.ok) { console.log("Failed to initialize signUpOrIn flow") console.log("Status Code: " + resp.code) console.log("Error Code: " + resp.error.errorCode) console.log("Error Description: " + resp.error.errorDescription) console.log("Error Message: " + resp.error.errorMessage)}else { console.log("Successfully initialized signUpOrIn flow") const linkId = resp.data.linkId; console.log("linkId " + linkId) const pendingRef = resp.data.pendingRef; console.log("pendingRef " + pendingRef)}
Call the verify function from your verify url. This means that this function needs to be called when the user
clicks the enchanted link. If the token is valid, the user will be authenticated and session returned to the polling thread (see next step).
On the route where you initialized the signIn, signUp, or signUpOrIn, you need to repeatedly poll for a valid session.
get_session(token) is called repeatedly until the user clicks the enchanted link URL they received, so that the
session on the initiating device can be directed to your desired page.
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 enchanted link Code, you will need to host a page to verify the enchanted link code using the enchanted link Verify Function.
// Args:// loginId (str): The loginId of the user being updatedconst loginId = "email@company.com"// email (str): The new email address. If an email address already exists for this end user, it will be overwrittenconst email = "newEmail@company.com"// refreshToken (str): The session's refresh token (used for verification)const refreshToken = "xxxxx"// updateOptions (UpdateOptions): this allows you to configure behavior during the authentication process.const updateOptions = { "addToLoginIDs": true, "onMergeUseExisting": true, "templateOptions": {"option": "Value1"} }const descopeSdk = useDescope();const resp = await descopeSdk.enchantedLink.update.email(loginId, email, refreshToken, updateOptions);if (!resp.ok) { console.log("Failed to start enchanted link email update") console.log("Status Code: " + resp.code) console.log("Error Code: " + resp.error.errorCode) console.log("Error Description: " + resp.error.errorDescription) console.log("Error Message: " + resp.error.errorMessage)}else { console.log("Successfully started enchanted link email update") console.log(resp.data)}
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.