POST
/v1/auth/magiclink/signup/email

Sign-Up

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

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

Verify the magic link token using the Verify Token endpoint.

See Also

  • See Magic link Authentication for details about implementing magic 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.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer \<Project ID\>

Try it

/v1/auth/magiclink/signup/email

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

emailstring

loginIdstring

userobject

redirectUrlstring

providerIdstring

loginOptionsobject

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/magiclink/signup/email" \
  -d '{
  "email": "string",
  "loginId": "string",
  "user": {
    "loginId": "string",
    "name": "string",
    "phone": "string",
    "email": "string",
    "givenName": "string",
    "middleName": "string",
    "familyName": "string"
  },
  "redirectUrl": "string",
  "providerId": "string",
  "loginOptions": {
    "customClaims": {},
    "templateOptions": {
      "property1": "string",
      "property2": "string"
    },
    "locale": "string",
    "pkceChallenge": "string"
  }
}'

{
  "maskedEmail": "string"
}

POST
/v1/auth/magiclink/signin/email

Sign-In

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

The endpoint will return a failure code if the email address is not 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

Verify the magic link token using the Verify Token endpoint.

See Also

  • See Magic link Authentication for details about implementing magic links.
  • See 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 for further details on loginOptions.
  • Use the Sign-Up endpoint to sign-up a new 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.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer \<Project ID\>

Try it

/v1/auth/magiclink/signin/email

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

loginIdstring

redirectUrlstring

loginOptionsobject

providerIdstring

ssoAppIdstring

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/magiclink/signin/email" \
  -d '{
  "loginId": "string",
  "redirectUrl": "string",
  "loginOptions": {
    "stepup": false,
    "customClaims": {},
    "mfa": false,
    "ssoAppId": "string",
    "templateOptions": {
      "property1": "string",
      "property2": "string"
    },
    "locale": "string",
    "pkceChallenge": "string"
  },
  "providerId": "string",
  "ssoAppId": "string"
}'

{
  "maskedEmail": "string"
}

POST
/v1/auth/magiclink/signup-in/email

Sign-In with Auto Sign-up

Initiate a process that implements both sign-in and sign-up using a single endpoint. Descope will generate and deliver a clickable magic link to the email address specified. If the email address is already registered (the end user has already registered) the user will be signed in. If the email address is not registered (the end user is not yet registered) the user will be signed up.

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

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

Verify the magic link token using the Verify Token endpoint.

See Also

  • See Magic link Authentication for details about implementing magic links.
  • See 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 for further details on loginOptions.
  • Use the Sign-Up endpoint if you want a sign-up flow that will fail if the end user is already registered.
  • Use the Sign-In endpoint if you want a sign-in flow that will fail if the end user isn't yet registered.

Endpoint Authentication

Use authorization bearer header with the following format:

Authorization: Bearer \<Project ID\>

Try it

/v1/auth/magiclink/signup-in/email

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

In: header

Request Body

loginIdstring

redirectUrlstring

loginOptionsobject

providerIdstring

ssoAppIdstring

Status codeDescription
200OK
curl -X POST "https://api.descope.com/v1/auth/magiclink/signup-in/email" \
  -d '{
  "loginId": "string",
  "redirectUrl": "string",
  "loginOptions": {
    "stepup": false,
    "customClaims": {},
    "mfa": false,
    "ssoAppId": "string",
    "templateOptions": {
      "property1": "string",
      "property2": "string"
    },
    "locale": "string",
    "pkceChallenge": "string"
  },
  "providerId": "string",
  "ssoAppId": "string"
}'

{
  "maskedEmail": "string"
}

POST
/v1/auth/magiclink/update/email

Update Email

Update the email address of an existing end user by sending a magic link to the new email address. Descope will generate and deliver a clickable magic link to the new email address specified. After successfully verifying the magic link token the new email address will be used to deliver new magic links via email.

The clickable magic link is made up of two parts - the URI you provide in the URI field and the magic link token generated by Descope. For example, if URI=https://app.mycompany.com/magiclink/verify, the clickable magic link will be https://app.mycompany.com/magiclink/verify?t=magic-link-token. Magic links expire in the time frame configured in the Descope console, so sending multiple magic links (for example, when an end user tries to sign-up a second or third time) does not invalidate prior magic 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.

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

Verify the magic link token using the Verify Token endpoint.

See Also

  • See Magic link Authentication for details about implementing magic 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/magiclink/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/magiclink/update/email" \
  -d '{
  "loginId": "string",
  "email": "string",
  "redirectUrl": "string",
  "addToLoginIDs": false,
  "onMergeUseExisting": false,
  "providerId": "string",
  "templateOptions": {
    "property1": "string",
    "property2": "string"
  },
  "locale": "string"
}'

{
  "maskedEmail": "string"
}

Was this helpful?

Next

Overview