Last updated 9 months ago

Mason features integrate with Authy to provide two-factor authentication as part of your login and register flow, or as a standalone feature to protect any high-risk action in your application.


  • Authy API Key - a unique key for Mason to access the Authy API on your behalf; you'll find this on your Authy application dashboard

  • Two-Factor Success Callback - a URL Mason will call when one of your users successfully completes two-factor authentication; you must implement this on your backend

How It Works

When your user first registers with your application, she must provide a phone number and an email address. These will be provided to Authy in exchange for an Authy User ID. If you use the Mason Register feature, Mason will do this for you. If not, you must do it yourself.

Integration and Setup

You provide two pieces of information for your Mason feature to integrate with Authy

  1. Authy API Key

  2. Two-Factor Success Callback (you may leave this blank if you haven't implemented it yet)

You must provide these values for each feature you'd like to perform two-factor authentication.

Follow the steps below to add an Authy integration to your Mason feature

  1. Create an Authy account

  2. Create a Mason Login, Register, or 2FA feature

  3. Open the Integrations panel in the left tool sidebar

  4. In the Authy section, enter the fields listed above

  5. Check the Require 2FA checkbox

  6. Save, Publish, and Export your feature

  7. Embed your feature where you want your users to authenticate

Authy User ID

In order to authenticate your user with Authy, you must provide your Mason feature with an Authy User ID. Depending on which feature you're using, providing an Authy User ID differs slightly.

Visit the documentation for your chosen feature below to see the implementation details

Server-side Validation

Mason will take your user through two-factor authentication on your behalf, and inform your server when it's successfully completed. You shouldn't unlock the user's account until you've received confirmation from Mason that two-factor authentication has succeeded.

Mason will send a server to server POST request to the URL you provided as the Two-Factor Success Callback containing the following JSON payload in the request body:

authyId: 'AUTHY_USER_ID',

To handle this request, your system should first validate that the verificationToken parameter matches your Mason Verification Token - this allows you to be sure the request originates from Mason. If it does, it should unlock the user's account to perform whatever action the user is attempting. Your system must respond with a 2xx HTTP response.