API Reference

Enchanted Link APIs

Overview

Using the Enchanted Link APIs enables users to sign in by clicking a link delivered to their email address. The email will include 3 different links, and the user will have to click the right one, based on the 2-digit number that is displayed when initiating the authentication process.

Read about Enchanted Link implementation types here

This implementation type has three phases:

  1. Initiate the process and send the enchanted link - this is initiated with the application sign-in or sign-up screens. T
  2. Poll for token verification and acquire the session and refresh tokens
  3. Verify the token

Note

The "Verify the token" phase happens in parallel and independent from the polling phase. As soon as it is done - the polling phase will result in the user sign-in details (session and refresh tokens).

Use Cases

  1. Sign up a new user
  2. Sign in an existing user
  3. Sign in with auto sign-up a new user if not exists
  4. Update user's email address
  5. Update user's phone number

Examples

Example - sign up

  1. Trigger the sign up process with the Sign-Up endpoint When action complete successfully, the body includes pendingRef and linkId. Show the linkId to the end user. An email will be generated with 3 different links and random numbers, one of them is the linkId.
  2. Regularly poll for the token verification, with the Poll Session endpoint. Use the pendingRef to identify the magic link you are waiting on. As soon as the user will click on the right link, and you call the "Verify Token" endpoint (#3 below), you will get the session and refresh tokens as a response.
  3. When the use clicks on the right link, call the Verify Token endpoint. When the token is validated, the endpoint will a successful code (200) and empty body.

Note

The example applies to all other use cases

Was this helpful?

Generate Embedded Link POST

### Generate an embedded link for an existing user Initiate a sign-in process by generating an embdedded link for an existing user utilizing a management key. The endpoint will return a token which can then be verified using the Magic Link [Verify Token](/api/magic-link/verification/verify-token) endpoint. ### Next Steps Verify the embedded link token using the [Verify Token](/api/magic-link/verification/verify-token) endpoint. ### See Also - See [Embedded link Authentication](/customize/auth/embeddedlink/) for details about implementing embedded links. - See [The User Object](/api/overview#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 <ProjectId:ManagementKey>`

Sign-Up POST

### Sign-up new end user by sending an enchanted link via email Initiate a sign-up process by sending an enchanted link to a new end user. Descope will generate and deliver 3 clickable links to the email address specified, each is numbered with random 2 digit number. When you initiate the enchanted link, the `linkId` will be returned. This `linkId` needs to be displayed to the user to indicate which link for the user to click once they receive the email. Only when the correct link is clicked will the user be successfully verified and logged in. 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](https://app.descope.com/settings/authentication/enchantedlink), 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 return body will include `linkId` and `pendigRef`. The `linkId` (a 2 digit number) should be presented to the user, so they will know which link to click in the delivered email. The endpoint will return a failure code if the email address is already registered. 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. ### Next Steps 1. Verify the enchanted link token using the [Verify Token](/api/enchanted-link/verify-token) endpoint. 2. Poll for the successful completion of the token verification using the [Poll Session](/api/enchanted-link/poll-session) endpoint, providing the `pendingRef` returned by the this endpoint. ### See Also - See [Enchanted link Authentication](/api/enchantedlink/) for details about implementing enchanted links. - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email addresses and phone number. - Use the [Sign-In](/api/enchanted-link/sign-in) endpoint to sign-in an existing end user. - Use the [Sign-In with Auto Sign-up](/api/enchanted-link/sign-in-auto-sign-up) endpoint to create a single sign-up and sign-in flow, which will create a new end user if they are not already registered. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID>`

On this page