Enchanted Link via Mobile SDKs

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.

The enchanted link flow within Descope for mobile SDK

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.

Use Cases

New user signup: The following actions must be completed, first User Sign-Up, then within the same route begin Polling for a valid session, and when the enchanted link is clicked User Verification
Existing user signin: The following actions must be completed, first User Sign-In, then within the same route begin Polling for a valid session, and when the enchanted link is clicked 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 within the same route begin Polling for a valid session, and when the enchanted link is clicked User Verification

Client SDK

Install SDK

// 1. Within XCode, go to File > Add Packages
// 2. Search for the URL of the git repo: https://github.com/descope/descope-swift
// 3. Configure your desired dependency rule
// 4. Click Add Package

// 1. Within Android Studio, go to File > Project Structure > Dependencies > Add Dependency > 1 Library Dependency
// 2. Search for the dependency: "com.descope"
// 3. Configure your desired dependency rules
// 4. Click "Ok"

// 1. From your Flutter project directory root, install the Descope SDK by running: flutter pub add descope
// 2. Or, add Descope to your pubspec.yml by including this line: descope: ^0.6.0
// View the package on pub.dev: https://pub.dev/packages/descope

// 1. From your React Native project directory root, install the Descope SDK by running: npm i @descope/react-native-sdk
// View the package: https://github.com/descope/descope-react-native

Import and initialize SDK

import DescopeKit
import AuthenticationServices

do {
    Descope.setup(projectId: "__ProjectID__") { config in
      // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
      config.baseURL = "https://auth.app.example.com"
    }
    print("Successfully initialized Descope")
} catch {
    print("Failed to initialize Descope")
    print(error)
}

import android.app.Application
import com.descope.Descope

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        try {
            Descope.setup(this, projectId = "__ProjectID__") {
              // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
              baseUrl = "https://auth.app.example.com"
              // Enable the logger
              if (BuildConfig.DEBUG) {
                logger = DescopeLogger()
              }
            }
        } catch (e: Exception) {
            Log.e("ERROR", e.stackTraceToString())
        }
    }
}

import 'package:descope/descope.dart';

// Where your application state is being created
Descope.setup('<Your-Project-Id>', (config) {
  // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
  config.baseUrl = 'https://auth.app.example.com';
});
await Descope.sessionManager.loadSession();

import { AuthProvider } from '@descope/react-native-sdk'

const AppRoot = () => {
  return (
    <AuthProvider
      projectId="__ProjectID__"
      // Optional: Only set baseURL if using a custom domain with Descope and managing token response with cookies
      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:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
let loginId = "email@company.com"
//    user: Optional user object to populate new user information.
let user = User("name": "Joe Person", "phone": "+15555555555", "email": "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'
let uri = "http://auth.company.com/api/verify_enchantedlink"

do {
  let enchantedResponse = try await Descope.enchantedLink.signUp(loginId: loginId, user: user, uri: uri)
  print("Successfully initiated Enchanted Sign Up")
  print("Enchanted Link linkId: " + enchantedResponse!.linkId)
  print("Enchanted Link pendingRef: " + enchantedResponse!.pendingRef)
} catch {
  print("Failed to initiate Enchanted Sign Up")
  print(error)
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
//    user: Optional user object to populate new user information.
//    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'
//    details: Optional object to populate new user information.
try {
    Descope.enchantedLink.signUp(
      loginId = "email@company.com", 
      uri = "http://auth.company.com/api/verify_enchantedlink",
      details = SignUpDetails(
        name = "firstName lastName",
        email = "email@company.com",
        phone = "+15555555555",
        givenName = "firstName",
        middleName = "middleName",
        familyName = "lastName"
      )
    )
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
  const loginId = 'email@company.com';
//    user: Optional user object to populate new user information.
  final details = SignUpDetails(name: "Name");
//    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';

  Descope.enchantedLink.signUp(loginId: loginId, uri: uri, details: details);

// 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 delivery
const 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 or phone - becomes the loginId for the user from here on and also used for delivery
let 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'
let uri = "http://auth.company.com/api/verify_enchantedlink"

guard let session = Descope.sessionManager.session else { return }
var signInOptions: [SignInOptions] = [
    .customClaims(["name": "{{user.name}}"]),
    .mfa(refreshJwt: session.refreshJwt),
    .stepup(refreshJwt: session.refreshJwt)
]

do {
  let enchantedResponse = try await Descope.enchantedLink.signIn(loginId: loginId, uri: uri, options: signInOptions)
  print("Successfully initiated Enchanted Link Sign In")
  print("Enchanted Link linkId: " + enchantedResponse!.linkId)
  print("Enchanted Link pendingRef: " + enchantedResponse!.pendingRef)
} catch {
  print("Failed to initiate Enchanted Sign Up")
  print(error)
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
//    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'
//    options: (Optional) options to get attributes like custom claims, stepup, mfa, and revoke sessions in response
try {
    Descope.enchantedLink.signIn(
      loginId = "email@company.com", 
      uri = "http://auth.company.com/api/verify_enchantedlink",
      options = listOf(
        SignInOptions.CustomClaims(mapOf("cc1" to "yes", "cc2" to true)),
        SignInOptions.StepUp(session.refreshJwt),
        SignInOptions.Mfa(session.refreshJwt),
        SignInOptions.RevokeOtherSessions
      )
    )
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
  const loginId = 'email@company.com';
//    user: Optional user object to populate new user information.
  const options = SignInOptions(customClaims: {'name': '{{user.name}}'});
//    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';

  Descope.enchantedLink.signIn(loginId: loginId, uri: uri, options: options);

// Args:
//    loginId: email - becomes the loginId for the user from here on and also used for delivery
const 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/mfa
 
const 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 or phone - becomes the loginId for the user from here on and also used for delivery
let 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'
let uri = "http://auth.company.com/api/verify_enchantedlink"

guard let session = Descope.sessionManager.session else { return }
var signInOptions: [SignInOptions] = [
    .customClaims(["name": "{{user.name}}"]),
    .mfa(refreshJwt: session.refreshJwt),
    .stepup(refreshJwt: session.refreshJwt)
]

do {
  let enchantedResponse = try await Descope.enchantedLink.signUpOrIn(loginId: loginId, uri: uri, options: signInOptions)
  print("Successfully initiated Enchanted Link Sign Up or In")
  print("Enchanted Link linkId: " + enchantedResponse!.linkId)
  print("Enchanted Link pendingRef: " + enchantedResponse!.pendingRef)
} catch {
  print("Failed to initiate Enchanted Sign Up or in")
  print(error)
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
//    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'
//    options: (Optional) options to get attributes like custom claims, stepup, mfa, and revoke sessions in response
try {
    Descope.enchantedLink.signUpOrIn(
      loginId = "email@company.com", 
      uri = "http://auth.company.com/api/verify_enchantedlink",
      options = listOf(
        SignInOptions.CustomClaims(mapOf("cc1" to "yes", "cc2" to true)),
        SignInOptions.StepUp(session.refreshJwt),
        SignInOptions.Mfa(session.refreshJwt),
        SignInOptions.RevokeOtherSessions
      )
    )
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// Args:
//    loginId: email or phone - becomes the loginId for the user from here on and also used for delivery
  const loginId = 'email@company.com';
//    user: Optional user object to populate new user information.
  const options = SignInOptions(customClaims: {'name': '{{user.name}}'});
//    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';

  Descope.enchantedLink.signUpOrIn(loginId: loginId, uri: uri, options: options);

// Args:
//    loginId: email - becomes the loginId for the user from here on and also used for delivery
const 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)
}

User Verification

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). This should be implemented from your web client or backend sdk when the link is clicked from the email received. The mobile application will then poll for a session.

Polling for valid session

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.

// Args:
//    pendingRef: Reference token received from signup or signin call.
let pendingRef = "xxxxx"

do {
  let descopeSession = try await Descope.enchantedLink.pollForSession(pendingRef: enchantedResponse!.pendingRef, timeout: 180)
  print("Successfully completed polling flow")
  print(descopeSession as Any)
} catch {
  print("Failed to complete polling flow")
  print(error)
}

// Args:
//    pendingRef: Reference token received from signup or signin call.
//    timeout: If timeout expires, an error is thrown
try {
      Descope.enchantedLink.pollForSession(
          pendingRef = "<pending_ref>",
          timeoutMilliseconds  "<timeoutMilliseconds>"
      )
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

 var enchantedLinkResponse = await Descope.enchantedLink
      .signUpOrIn(loginId: loginId, uri: uri, options: options);


// Args:
//    pendingRef: Reference token received from signup or signin call.
      var pendingRef = enchantedLinkResponse.pendingRef;

//    timeout: If timeout expires, an error is thrown
const timeout = Duration(seconds: "<timeoutSeconds>");

final authResponse = await Descope.enchantedLink.pollForSession(
      pendingRef: pendingRef, timeout: timeout);

// Args:
//    pendingRef: Reference token received from signup or signin call.
const pendingRef = "xxxxx"
 
const descopeSdk = useDescope();
const resp = await descopeSdk.enchantedLink.waitForSession(pendingRef);
if (!resp.ok) {
  console.log("Failed to complete polling 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 completed polling flow")
  console.log(resp)
}

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 enchanted 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.

// Args:
//    email: the new email address you want to associate with the user
let email = "newEmail@company.com"
//    loginId: email or phone - the loginId of the user
let 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'
let uri = "http://auth.company.com/api/verify_enchantedlink"
//    refreshJwt: The refreshJwt of the user to be updated
let refreshJwt = "xxxxxx"

do {
  let enchantedResponse = try await Descope.enchantedLink.updateEmail(email, loginId: loginId, uri: uri, refreshJwt: refreshJwt)
  print("Successfully started Enchanted Link Email Update")
  print("Enchanted Link linkId: " + enchantedResponse!.linkId)
  print("Enchanted Link pendingRef: " + enchantedResponse!.pendingRef)
} catch {
  print("Successfully started Enchanted Link Email Update")
  print(error)
}

// Args:
//    email: the new email address you want to associate with the user
//    loginId: email or phone - the loginId of the user
//    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'
//    refreshJwt: The refreshJwt of the user to be updated
//    options: optional options for loginId and merging behavior
try {
      Descope.enchantedLink.updateEmail(
          email = "email@company.com",
          loginId = "email@company.com",
          uri = "http://auth.company.com/api/verify_enchantedlink",
          refreshJwt = "<refreshJwt>"
          options = UpdateOptions(
            addToLoginIds = true,
            onMergeUseExisting = true
          )
      )
} catch (e: Exception) {
    Log.e("ERROR", e.stackTraceToString())
}

// Args:
//    email: the new email address you want to associate with the user
const email = "newEmail@company.com";
//    loginId: email or phone - the loginId of the user
const 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";
//    refreshJwt: The refreshJwt of the user to be updated
final refreshJwt = Descope.sessionManager.session!.refreshJwt;
/// You can optionally pass the [options] parameter to add the new phone number
/// as a `loginId` for the existing user, and to determine how to resolve conflicts
/// if another user already exists with the same `loginId`. Check out the
// Update Options (https://github.com/descope/descope-flutter/blob/main/lib/src/types/others.dart) type for more details.
final options = UpdateOptions(
  addToLoginIds: true,
  onMergeUseExisting: true
);
Descope.enchantedLink.updateEmail(
      email: email,
      refreshJwt: refreshJwt,
      loginId: loginId,
      uri: uri,
      options: options);

// Args:
//   loginId (str): The loginId of the user being updated
const loginId = "email@company.com"
//   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
const 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)
}

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.

Need help?

Was this helpful?

Checkpoint

On this page