API Reference

Magic Link APIs

Overview

Using the Magic Link APIs allow enables users to sign in by clicking a link delivered to their email or phone.

Read about Magic Link implementation types here

This authentication method type has two phases:

  1. Initiate the process and send the magic link - this is initiated with the application sign-in or sign-up screens
  2. Verify the token and return the session and refresh tokens (signed-in user)

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, over email

  1. Trigger the sign up process with the Sign-Up endpoint When action complete successfully, a magic link will be generated with a token, and delivered to the user's email.
  2. When the use clicks on the magic link, call the Verify Magic Link endpoint. When the token is validated, the endpoint will return a signed-in user (session and refresh tokens).
Was this helpful?

Update Phone POST

### Update phone number of Existing User Update the phone number of an existing end user by sending an OTP code to the new phone number. After successfully verifying the code the new phone number will be used to deliver new OTP messages via Voice. 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. This endpoint will return an empty response object when it completes successfully. 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](/manage/users#associating-multiple-login-ids-for-a-user). ### Next Steps Verify the OTP code using the [Verify OTP Code](/api/otp/phone/verify-otp) endpoint to complete the update process. After successfully verifying the code the newphone number will replace the original phone number. ### See Also - See [The User Object](/api/overview#the-user-object) for further details on how to identify users and their contact information such as email address and phone number. - Successful execution will return an empty body - To try this endpoint - need to provide `Project ID:Refresh JWT` as bearer. You can acquire the Session JWT by signing in the user and collecting it from the response. ### Endpoint Authentication Use authorization bearer header with the following format: `Authorization: Bearer <Project ID:Refresh JWT>`

Sign-Up POST

### Sign-up new end user by sending a magic link via email 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](https://app.descope.com/settings/authentication/magiclink), 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](/api/magic-link/verification/verify-token) endpoint. ### See Also - See [Magic link Authentication](/auth-methods/magic-link/with-sdks/client#introduction) for details about implementing magic 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/magic-link/email/sign-in) endpoint to sign-in an existing end user. - Use the [Sign-In with Auto Sign-up](/api/magic-link/email/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