Login Form

Login Form

#Overview

Learn how to integrate Magic’s custom, production-ready passwordless login experience. Up and running with just 2 script tags.

The Login Form is a low-code/no-code solution. It supports Web (JavaScript) though is not compatible with React.

Prefer to use Magic with your existing UI? Check out our client-side SDK for a white-labeled auth experience.

#Pre-requisites

All you need to get started is a Magic account.

New to Magic? Sign up for free.

#Usage

#Add login form script

Create a new login page and add the script tag below. Your publishable API key can be found on the Home page of your Magic Dashboard.

HTML
01<!-- /login.html -->
02<script
03  src="https://auth.magic.link/pnp/login"
04  data-magic-publishable-api-key="[YOUR_PUBLISHABLE_API_KEY_HERE]"
05  data-terms-of-service-uri="/path/to/your/terms-of-service"
06  data-privacy-policy-uri="/path/to/your/privacy-policy"
07  data-redirect-uri="/callback"> <!-- Replace with the location of your callback.html -->
08</script>

This will generate a pre-built login form based on the branding and login methods you’ve enabled via Dashboard. Users will automatically be redirected to the URI provided in data-redirect-uri upon authorization. If no data-redirect-uri is specified, a relative path — /callback — is automatically used as a fallback.

#Add callback script

Next, create a page containing the script tag below to handle the authentication callback.

HTML
01<!-- /callback.html -->
02<script
03  src="https://auth.magic.link/pnp/callback"
04  data-magic-publishable-api-key="[YOUR_PUBLISHABLE_API_KEY_HERE]">
05</script>
note

Providing a data-login-uri or data-redirect-uri parameter will automatically redirect the user if a problem occurs during authentication callback. You can use this to send the user back to the beginning of your login flow.

If no data-login-uri or data-redirect-uri is specified, the current value of window.location.origin is used instead.

Custom callback logic

Upon a user's successful login, you may wish to perform your own client-side and server-side business logic. To do so, you can hook into the @magic/ready event on the window object of the page containing your https://auth.magic.link/pnp/callback script.

HTML
01<script>
02  window.addEventListener('@magic/ready', (event) => {
03    const { magic, idToken, userMetadata, oauth } = event.detail;
04    // ...
05  });
06</script>

The @magic/ready event contains an object of custom data attached to event.detail. The following fields are surfaced:

  • magic - An instance of Magic JS which can be used to interface with any Magic methods at a low-level
  • idToken - A DID token for the user
  • userMetadata - Up-to-date user metadata for the user
  • oauth - An OAuth response for the user, if the login method was initiated through an OAuth provider — otherwise, this field is undefined

#Logging users out

You can optionally provide an endpoint in your app to log users out of their Magic session. Users will automatically be redirected to the URI provided in data-login-uri or data-redirect-uri upon successful logout. If no data-login-uri or data-redirect-uri is specified, the current value of window.location.origin is used instead.

HTML
01<!-- /logout.html -->
02<script
03  src="https://auth.magic.link/pnp/logout"
04  data-magic-publishable-api-key="[YOUR_PUBLISHABLE_API_KEY_HERE]"
05  data-redirect-uri="/login"> <!-- Replace with the location of your login.html -->
06</script>

#Implementing user settings

Magic provides an out-of-the-box settings widget through which your users can self-service different functions of their account, including enabling or disabling multi-factor auth (MFA). Users will automatically be redirected to the URI provided in data-redirect-uri (or, if no value is provided, a relative path of /callback) upon dismissal of the settings widget. In your custom callback logic, you will have access to a prevUserMetadata field on the @magic/ready event data so that settings updates can be manually diffed and utilized in your app. If a user is not currently logged-in upon accessing the settings widget, they will be automatically redirected to the URI provided in data-login-uri (or, if no value is provided, window.location.origin is used instead).

HTML
01<!-- /settings.html -->
02<script
03  src="https://auth.magic.link/pnp/settings"
04  data-magic-publishable-api-key="[YOUR_PUBLISHABLE_API_KEY_HERE]"
05  data-login-uri="/login"
06  data-redirect-uri="/callback"> <!-- Replace with the location of your login.html -->
07</script>

#Utilizing old vs. new user metadata

Upon a user's dismissal of the settings widget, you may wish to perform some action based on a change in the user's metadata. To do so, you can hook into the @magic/ready event on the window object of the page containing your https://auth.magic.link/pnp/callback script.

HTML
01<script>
02  window.addEventListener('@magic/ready', (event) => {
03    const { prevUserMetada, userMetadata } = event.detail;
04    // Compare `prevUserMetadata` with `userMetadata`,
05    // then call into your backend service to update a user's information.
06  });
07</script>

#Script Options

Magic Login Form accepts a number of arguments via data-* attributes given to the script tag:

  • data-magic-publishable-api-key - The publishable API key for your app found in Magic Dashboard
  • data-redirect-uri - The location to which a user is redirected after completing a contextual action. For example, upon successful authorization, the user should be redirected to the auth callback page given to this parameter.
  • data-login-uri - Similar to data-redirect-uri, but implies the location is a login page. For example, if a problem occurs during authentication, the user may wish to "start over" at the location given to this parameter.
  • data-terms-of-service-uri - A location containing your app's terms of service. Magic Login Form will surface a link with target="_blank" to this page.
  • data-privacy-policy-uri - A location containing your app's privacy policy. Magic Login Form will surface a link with target="_blank" to this page.
  • data-locale - The ISO language code to be used as a locale hint for Magic SDK. This is the same locale parameter given to the Magic JS constructor.

#Customization

#Login methods

Your Magic Login Form will automatically update based on your app’s Dashboard configuration.

Email and SMS login are managed via the Passwordless Logins page. 10+ social login providers are available through the Social Logins page.

Magic Login Form does not yet support WebAuthn.

#Branding

Head to the Branding section of Dashboard to update your brand color, logo, and theming.

#Login page background

You can customize the styling of your login page through CSS or other means, to match your brand’s look and feel.

caution

Do not put any interactive elements or UI on your login page. Users will only be able to interact with the login form.

#FAQs

#Can I customize the order that login methods are shown?

Magic’s login form prioritizes passwordless login options, with Email as the default login. Social logins are presented based on the order in which they were enabled.

If a user is recognized, we’ll automatically prioritize the login method they last used to sign in.

#Is this login form required to use Magic for authentication?

No, Magic’s plug and play login form is totally optional!

To use Magic with your own frontend UI, you should integrate using our client-side SDK.

#Can I add a privacy policy or terms of service to my login form?

Yes, in a pinch! See Usage for an example usage of the data-terms-of-service-uri and data-privacy-policy-uri attributes.

#Where can I go for help implementing Magic?

Join Magic on Discord to get help, provide feedback, share memes, and stay up to date on the latest Magic releases.

#Resources