API ReferenceEnchanted Link
POST
/v1/auth/enchantedlink/update/email

Update the email address of an existing end user by sending an enchanted link to the new email address. Descope will generate and deliver 3 clickable links to the email address specified, each is numbered with random 2 digit number. Only the right link (based on the number returned will be successfully verified when clicked)

Each clickable link is made up of two parts - the URI you provide in the URI field and the enchanted link token generated by Descope. For example, if URI=https://app.mycompany.com/enchantedlink/verify, the clickable enchanted link will be https://app.mycompany.com/enchantedlink/verify?t=enchanted-link-token. Enchanted links expire in the time frame configured in the Descope console, so sending multiple enchanted links (for example, when an end user tries to sign-up a second or third time) does not invalidate links that have already been sent.

The bearer token requires both the ProjectId and refresh JWT in the format \<Project ID\>:<JWT>, and can therefore only be run for end users who are currently signed-in.

Note that URI is an optional parameter. If omitted - the project setting will apply. If provided - it should to be part of the allowed Approved Domains configured in the project settings.

Once the token is successfully verified - the email address will be updated.

Descope allows you to associating multiple login IDs for a user during API update calls. For details on how this feature works, please review the details here.

Next Steps

  1. Verify the enchanted link token using the Verify Token endpoint.
  2. Poll for the successful completion of the token verification using the Poll Session endpoint, providing the pendingRef returned by the this endpoint.

See Also

  • See Enchanted link Authentication for details about implementing enchanted links.
  • See The User Object for further details on how to identify users and their contact information such as email addresses and phone number.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer <Project ID:Refresh JWT>

Try it

/v1/auth/enchantedlink/update/email

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

loginIdstring

emailstring

redirectUrlstring

addToLoginIDsboolean

Default: false

onMergeUseExistingboolean

Default: false

providerIdstring

templateOptionsobject

localestring

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/enchantedlink/update/email" \
  -d '{
  "loginId": "string",
  "email": "string",
  "redirectUrl": "string",
  "addToLoginIDs": false,
  "onMergeUseExisting": false,
  "providerId": "string",
  "templateOptions": {
    "property1": "string",
    "property2": "string"
  },
  "locale": "string"
}'

{
  "pendingRef": "string",
  "linkId": "string",
  "maskedEmail": "string"
}

Was this helpful?

Previous

Poll Session

Next

OAuth Social Login API Overview