Magiclink Emails

How Magiclink Email Registration Works

Registering users to use Magiclink Emails involves sending the user an email asking them to register. The user clicks a link in the email that contains a query string value with a registration token that is unique to the registration request. When this link is clicked, it takes the user to a page you have defined in the developer dashboard as an allowed registration redirect url.

New User Registration

To start the registration process, call the magiclink_email start method by using the api or one of our libraries.
For Magiclink Email registrations, you must supply a valid email address that is not currently being used.

Properties

Property name	Description
`email_address`	The email address of the user you wish to register
`timeout_in_seconds`	The time this registration email will be valid for. Default is 5 minutes.
`registration_redirect_url`	The url that will be used when the user clicks the action button in the Magiclink Email. This url must be on the allowed list. To set this, please login to the dashboard and create a new registration redirect allowed url.
`action_name`	The action name for this registration request. This will show up in the subject of the email. For example, an action name of "Register" and a project name of "My Test Project" will have a subject of "Register at My Test Project".
`short_msg`	A short message you can optionally include in the email that is sent to the user.
`context_data`	This is a key-value pair you can use to maintain context from signup start to completion. For example, if you need to store some data, such as a refer for signup, you can set this value in here. When you validate the `magiclink_registration_token` this data will be returned to you.
`ip_address`	You can optionally include the ip address that is used during registration. This will be compared to the IP during validation to increase security and help prevent spam
`user_agent`	You can optionally include the user agent of the client during registration. This will be compared to the user agent during validation to increase security and help prevent spam.

{
  "email_address": "string",
  "timeout_in_seconds": 0,
  "registration_redirect_url": "string",
  "action_name": "string",
  "short_msg": "string",
  "context_data": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "ip_address": "string",
  "user_agent": "string"
}

A Magiclink Email registration request will be sent to the provided email address. The registration_redirect_url that was provided in the request call will be the url the use is redirected to once they click the registration button.

Existing User Registration

Note This is only for users who are already registered using another auth method, such as WebAuthn or Authenticator. You can then add magiclink email ability to a user using the existing user flow.

Validate a Magiclink Email Registration Token

You must create a page that corresponds to the registration_redirect_url so you can handle the registration button click from the email. The link inside the email will contain a query string with some values you need to grab.

Query String value	Description
`registration_validation_token`	The unique registration token for this request

Example

If your registration_redirect_url is set to https://www.example.com/magiclinkemail-registration then you need to build a page that corresponds to that url.
When the Magiclink Registration Email is sent, it will contain a button with the action name you have specified. When the button is clicked, it will load a webpage that goes to the redirect url you have specified, along with some query string data, including a registration_validation_token. You need to capture this value. Once you have this value, you need to call the Auth Armor Backend API to validate the registration token.

API: link

Once you validate the registration token, the user will be created. The API will return the following:

{
  "magiclink_email_registration_type": "new_user",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "username": "string",
  "email_address": "string",
  "context_data": {
    "additionalProp": "string"
  }
}

If you passed context data during registration, it will be returned upon validation.