Enchanted Link

pip3 install descope

go get github.com/descope/go-sdk

// Include the following in your `pom.xml` (Maven)
<dependency>
    <artifactId>java-sdk</artifactId>
    <groupId>com.descope</groupId>
    <version>sdk-version</version> // Check https://github.com/descope/descope-java/releases for the latest versions
</dependency>

from descope import (
    REFRESH_SESSION_TOKEN_NAME,
    SESSION_TOKEN_NAME,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    AssociatedTenant,
    RoleMapping,
    AttributeMapping,
    LoginOptions
)
try:
    # You can configure the baseURL by setting the env variable Ex: export DESCOPE_BASE_URI="https://auth.company.com  - this is useful when you utilize CNAME within your Descope project."
    descope_client = DescopeClient(project_id='__ProjectID__')
except Exception as error:
    # handle the error
    print ("failed to initialize. Error:")
    print (error)

import "github.com/descope/go-sdk/descope"
import "github.com/descope/go-sdk/descope/client"

// Utilizing the context package allows for the transmission of context capabilities like cancellation
//      signals during the function call. In cases where context is absent, the context.Background()
//      function serves as a viable alternative.
//      Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
import (
	"context"
)

// DescopeBaseURL // within the client.Config, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.

descopeClient, err := client.NewWithConfig(&client.Config{ProjectID:"__ProjectID__"})
if err != nil {
    // handle the error
    log.Println("failed to initialize: " + err.Error())
}

import com.descope.client.Config;
import com.descope.client.DescopeClient;

var descopeClient = new DescopeClient(Config.builder().projectId("__ProjectID__").build());

# Args:
#   user: Optional user object to populate new user information.
user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}
#   login_id: email - becomes the login_id for the user from here on and also used for delivery
login_id = "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
uri = "http://auth.company.com/api/verify_enchantedlink"
#   signup_options (SignUpOptions): this allows you to configure behavior during the authentication process.
signup_options = {
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }

try:
  resp = descope_client.enchantedlink.sign_up(login_id=login_id, uri=uri, user=user, signup_options=signup_options)
  print ("Successfully initialized signup flow")
  link_identifier = resp["linkId"]
  pending_ref = resp["pendingRef"]
  print ("Link Identifier: " + str(link_identifier))
  print ("Pending Ref: " + str(pending_ref))
  # initiate polling - see below
except AuthException as error:
  print ("Failed to initialize signup flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//   ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//  loginID: email or phone - Used as the unique ID for the user from here on and also used for delivery
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'
URI := "http://auth.company.com/api/verify_enchantedlink"
//  user: Optional user object to populate new user information.
user := &descope.User{Name:"Joe", Email:"email@company.com", Phone:"+15555555555"}
//    signUpOptions: this allows you to configure behavior during the authentication process.
signUpOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

res, err := descopeClient.Auth.EnchantedLink().SignUp(ctx, loginID, URI, user, signUpOptions)
if (err != nil){
  fmt.Println("Failed to initialize signup flow: ", err)
} else {
  fmt.Println("Successfully initialized signup flow: ", res)
}

// If configured globally, the redirect URI is optional. If provided however, it will be used
// instead of any global configuration.
// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();

var signUpOptions = SignupOptions.builder()
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

EnchantedLinkService els = descopeClient.getAuthenticationServices().getEnchantedLinkService();
EnchantedLinkResponse res = null;
try {
  String uri = "http://auth.company.com/api/verify_enchantedlink";
  res = els.signUp(loginId, uri, user, signUpOptions);

} catch (DescopeException de) {
  // Handle the error
}

# Args:
#   login_id: email - becomes the loginId for the user from here on and also used for delivery
login_id = "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
uri = "http://auth.company.com/api/verify_enchantedlink"
#   login_options (LoginOptions): this allows you to configure behavior during the authentication process.
login_options = {
      "stepup": false,
      "mfa": false,
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }
#   refresh_token (optional): the user's current refresh token in the event of stepup/mfa

try:
  resp = descope_client.enchantedlink.sign_in(login_id=login_id, uri=uri, login_options=login_options)
  print ("Successfully initialized signin flow")
  link_identifier = resp["linkId"]
  pending_ref = resp["pendingRef"]
  print ("Link Identifier: " + str(link_identifier))
  print ("Pending Ref: " + str(pending_ref))
  # initiate polling - see below
except AuthException as error:
  print ("Failed to initialize signin flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID: email or phone - the loginId for the user
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'
URI := "http://auth.company.com/api/verify_enchantedlink"
//    r: HttpRequest for the update call. This request should contain refresh token for the authenticated user.
//    loginOptions: this allows you to configure behavior during the authentication process.
loginOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

res, err := descopeClient.Auth.EnchantedLink().SignIn(ctx, loginID, URI, r, loginOptions)
if (err != nil){
  fmt.Println("Failed to initialize signin flow: ", err)
} else {
  fmt.Println("Successfully initialized signin flow: ", res)
}

// If configured globally, the redirect URI is optional. If provided however, it will be used
// instead of any global configuration.
// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();
var loginOptions = LoginOptions.builder()
				.stepUp(true)
        .mfa(true)
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

EnchantedLinkService els = descopeClient.getAuthenticationServices().getEnchantedLinkService();
EnchantedLinkResponse res = null;
try {
  String uri = "http://auth.company.com/api/verify_enchantedlink";
  res = els.signIn(loginId, uri, loginOptions);

} catch (DescopeException de) {
  // Handle the error
}

# Args:
#   login_id: email - becomes the login_id for the user from here on and also used for delivery
login_id = "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
uri = "http://auth.company.com/api/verify_enchantedlink"
#   signup_options (SignUpOptions): this allows you to configure behavior during the authentication process.
signup_options = {
      "custom_claims": {"claim": "Value1"},
      "template_options": {"option": "Value1"}
    }

try:
  resp = descope_client.enchantedlink.sign_up_or_in(login_id=login_id, uri=uri, signup_options=signup_options)
  print ("Successfully initialized signup or in flow")
  link_identifier = resp["linkId"]
  pending_ref = resp["pendingRef"]
  print ("Link Identifier: " + str(link_identifier))
  print ("Pending Ref: " + str(pending_ref))
  # initiate polling - see below
except AuthException as error:
  print ("Failed to initialize signup or in flow")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//   ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//  loginID: email or phone - Used as the unique ID for the user from here on and also used for delivery
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'
URI := "http://auth.company.com/api/verify_enchantedlink"
//    signUpOptions: this allows you to configure behavior during the authentication process.
signUpOptions := &descope.LoginOptions{
    Stepup: true,
    MFA: true,
    CustomClaims: map[string]any{}{"test": "testClaim"},
    TemplateOptions: map[string]any{"option": "Value1"}
  }

res, err := descopeClient.Auth.EnchantedLink().SignUpOrIn(ctx, loginID, URI. signUpOptions)
if (err != nil){
  fmt.Println("Failed to initialize signup or in flow: ", err)
} else {
  fmt.Println("Successfully initialized signup or in flow: ", res)
}

// If configured globally, the redirect URI is optional. If provided however, it will be used
// instead of any global configuration.
// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";

var signUpOptions = SignupOptions.builder()
        .customClaims(
           new HashMap<String, Object>() {{
                put("custom-key1", "custom-value1");}}
        )
        .templateOptions(
           new HashMap<String, String>() {{
                put("option", "Value1");}}
        )
				.build();

EnchantedLinkService els = descopeClient.getAuthenticationServices().getEnchantedLinkService();
EnchantedLinkResponse res = null;
try {
  String uri = "http://auth.company.com/api/verify_enchantedlink";
  res = els.signUpOrIn(loginId, uri, signUpOptions);

} catch (DescopeException de) {
  // Handle the error
}

# Args:
#   token:  URL parameter containing the enchanted link token, for example, https://auth.yourcompany.com/api/verify_enchantedlink?t=token.
token = "xxxx"

try:
  resp = descope_client.enchantedlink.verify(token=token)
  print ("Successfully verified user")
except AuthException as error:
  print ("Failed to verify user")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//   ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//   token:  URL parameter containing the enchanted link token, for example, https://auth.yourcompany.com/api/verify_enchantedlink?t=token.
token = "xxxx"

err := descopeClient.Auth.EnchantedLink().Verify(ctx, token)
if (err != nil){
  fmt.Println("Failed to verify user: ", err)
} else {
  fmt.Println("Successfully verified user")
}

// Args:
//   token:  URL parameter containing the enchanted link token, for example, https://auth.yourcompany.com/api/verify_enchantedlink?t=token.
token = "xxxx"
EnchantedLinkService els = descopeClient.getAuthenticationServices().getEnchantedLinkService();

try {
    els.verify(token);
} catch (DescopeException de) {
    // Token is invalid, handle the error
}

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

i = 0
done = False
max_tries = 18

while not done and i < max_tries:
  try:
    i = i + 1
    time.sleep(10)
    jwt_response = descope_client.enchantedlink.get_session(pending_ref)
    done = True
  except AuthException as e: # Poll while still receiving 401 Unauthorized
    if e.status_code != 401: # Other failures means something's wrong, abort
      logging.info(f"Failed pending session, err: {e}")
      done = True

if jwt_response[SESSION_TOKEN_NAME].get("jwt"):
  print ("Successfully completed polling flow")
  session_token = jwt_response[SESSION_TOKEN_NAME].get("jwt")
  print ("Session Token: " + str(session_token))
  refresh_token = jwt_response[REFRESH_SESSION_TOKEN_NAME].get("jwt")
  print ("Refresh Token: " + str(refresh_token))
else:
  print ("Failed to complete polling flow")
  print ("Status Code: " + jwt_response.code)
  print ("Error Code: " + jwt_response.error.errorCode)
  print ("Error Description: " + jwt_response.error.errorDescription)
  print ("Error Message: " + jwt_response.error.errorMessage)

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    pendingRef: Reference token received from signup or signin call.
pendingRef = "xxxxx"
//    w: ResponseWriter to update with correct session details. You can return this to your client for setting the cookies which are used for session validation. This code should go into your application server route handling the verification of code.

for i := retriesCount; i > 0; i-- {
  authInfo, err := client.Auth.EnchantedLink().GetSession(ctx, pendingRef, w)
  if err == nil {
    // The user successfully authenticated using the correct link
    // The optional `w http.ResponseWriter` adds the session and refresh cookies to the response automatically.
    // Otherwise they're available via authInfo
    fmt.Println("Successfully completed polling flow: ", authInfo)
    break
  }
  if err == errors.EnchantedLinkUnauthorized && i > 1 {
    // poll again after X seconds
    time.Sleep(time.Second * time.Duration(retryInterval))
    continue
  }
  if err != nil {
    fmt.Println("Failed to complete polling flow: ", err)
    break
  }
}

// After sending the link, you must poll to receive a valid session using the PendingRef from the previous step. A valid session will be returned only after the user clicks the right link.

EnchantedLinkService els = descopeClient.getAuthenticationServices().getEnchantedLinkService();
// Poll for a certain number of tries / time frame
for (int i = retriesCount; i > 0; i--) {
    try {
        AuthenticationInfo info = els.getSession(res.getPendingRef());
    } catch (DescopeException de) {
        if (i > 1) {
            // Poll again after X seconds
            TimeUnit.SECONDS.sleep(retryInterval);
            continue;
        }
        else {
            // Handle the error
            break;
        }
    }
}

// To verify an enchanted link, your redirect page must call the validation function on the token (t) parameter (https://your-redirect-address.com/verify?t=<token>). Once the token is verified, the session polling will receive a valid response.

try {
    els.verify(token);
} catch (DescopeException de) {
    // Token is invalid, handle the error
}

# Args:
#   login_id (str): The login_id of the user being updated
login_id = "email@company.com"
#   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
email = "newEmail@company.com"
#   refresh_token (str): The session's refresh token (used for verification)
refresh_token = "xxxxx"
#   add_to_login_ids (boolean): if true, the email will be appended to the login ID array.
add_to_login_ids = True
#   on_merge_use_existing (boolean): if true, on merge, the existing user's information (roles, tenants, etc) will be retained
on_merge_use_existing = True
#   template_options (dict): email template options
template_options = {"option": "Value1"}

try:
    jwt_response = descope_client.enchantedlink.update_user_email(login_id=login_id, email=email, refresh_token=refresh_token, add_to_login_ids=add_to_login_ids, on_merge_use_existing=on_merge_use_existing, template_options=template_options)
    print ("Successfully started enchanted link email update")
    print(json.dumps(jwt_response, indent=4))
except AuthException as error:
    print ("Failed to start enchanted link email update")
    print ("Status Code: " + str(error.status_code))
    print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//   loginId (str): The loginId of the user being updated
loginID := "email@company.com"
//   email (str): The new email address. If an email address already exists for this end user, it will be overwritten
email := "newEmail@company.com"
//   updateOptions (&descope.UpdateOptions): Optional login options for MFA, stepup, or custom claims.
updateOptions := &descope.UpdateOptions{}
updateOptions.AddToLoginIDs = false
updateOptions.OnMergeUseExisting = false
updateOptions.TemplateOptions = map[string]any{"option": "Value1"}
//   request (*http.Request): Request is needed to obtain JWT and send it to Descope, for verification


res, err := descopeClient.Auth.EnchantedLink().UpdateUserEmail(ctx, loginID, email, updateOptions, request)
if (err != nil){
  fmt.Println("Failed to start enchanted link email update: ", err)
} else {
  fmt.Println("Successfully started enchanted link email update", res)
}

// Will throw DescopeException if there is an error with update
EnchantedLinkService mls = descopeClient.getAuthenticationServices().getEnchantedLinkService();

try {
  AuthenticationInfo info = mls.updateUserEmail(loginId, email, refreshToken, UpdateOptions);
} catch (DescopeException de) {
  // Handle the error
}