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

Authorization

Descope Project ID
AuthorizationBearer <token>

Project ID as bearer token.

In: header

Request Body

application/json

email?string
loginId?string
user?object
redirectUrl?string
providerId?string
loginOptions?object

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, 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 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.
  • Use the Sign-In endpoint to sign-in an existing end user.
  • Use the Sign-In with 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.
curl -X POST "https://api.descope.com/v1/auth/enchantedlink/signup/email" \  -H "Content-Type: application/json" \  -d '{}'
{  "pendingRef": "string",  "linkId": "string",  "maskedEmail": "string"}
export interface Response {pendingRef?: stringlinkId?: stringmaskedEmail?: string}
Was this helpful?

Enchanted Link Authentication API Overview

Use the Descope REST API to build enchanted link authentication for your application.

Sign-In POST

### Sign-in existing user by sending an enchanted link via email Initiate a sign-in 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. - See [User Login Options](/api/overview#user-login-options) for further details on loginOptions. - Use the [Sign-Up](/api/enchanted-link/sign-up) endpoint to sign-up a new 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.