Rate this page:

Authy TOTP Ruby Quickstart

For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience, and new features including:

  • Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, PHP, and Go.
  • Access via the Twilio CLI.
  • Improved visibility and insights.
  • A push authentication SDK embeddable in your own application.

You are currently viewing the Authy API. New features and development will be added only to the Verify API. Check out the FAQ for more information and the migrating to Verify guide to get started.


Authy is a simple REST API that does all the heavy lifting, so you can add two-factor authentication to your website or app in just a few hours. We have a number of resources, such as JavaScript helpers and API libraries for most languages. This guide will make use of these resources as we build a simple web app using the Authy API.

Full source code for this app can be found here


You will find everything you need in on github


There are two main parts to implement an Authy API integration:

  • Adding new users: involves creating an html form that takes the user's phone number / email and submits it to the Authy API.

  • Verifying users: involves adding a field to the login form were the user enters the token which is in turn submitted to Authy for verification.

Part 1: Adding a new user

First we are going to create a page in the users control panel (we will call it /enableauthy). In this page we'll create a simple form that collects the phone number and area code.

This form uses the Authy JavaScript samples found here. The html IDs authy-cellphone and authy-countries are special IDs recognized by this JavaScript.

= text_field "cellphone", :placeholder => "Enter your cellphone", :id => "authy-cellphone"

= text_field "country_code", :id => "authy-countries", :placeholder => "Enter your country"

= submit "Submit", :class => "btn"

JavaScript ID tag helpers

The scripts use ID s to help you easily build this form. These are the id's used

  • authy-cellphone: If set on the text-field were the user inputs his cellphone, it will automatically run phone validations on the client-side.

  • authy-countries: If set on the text-field were the user inputs his area code, it will produce an auto-complete drop down with a list of countries and their area-codes. This simplifies the user entering his area-code.

At this point you can send the users email, phone number and country code to Authy.

def register_authy
  @authy_user = Authy::API.register_user(
    :email =>,
    :cellphone => params[:user][:cellphone],
    :country_code => params[:user][:country_code]

  if @authy_user.ok?
    current_user.authy_id =
    @errors = @authy_user.errors
    render 'enable_authy'

If everything goes well, the API will return the user's Authy ID. This is represented as an integer which you need to store in your users database or directory. In the case of an error, a hash in plain English is returned. The language used is designed for you to display to the user to help them resolve the situation.

Part 2: Verifying users

After you have registered the user in the Authy service and stored the resulting Authy ID against the user's profile in your application, the next time you process the user login, you use the Authy ID to verify the two-factor token they should provide.

Implementing the request for a second factor during the login can vary depending on the design of your application and the end user experience you wish to create. In this example we plan to support users who opt-in for two-factor authentication. Therefore there will be a mix of user accounts that are enabled and some that are not. The easiest way to implement this is to separate the authentication process across two screens.

  1. The first screen is your usual login form where the user inputs username and password.

  2. The second screen the user inputs the Authy token, assuming they have opt-ed into Authy and they've gone through the user registration process.

Remember you need to manage the link between your user identities and the Authy user. Your database or user directory should ensure the AuthyID is stored with each user profile that has been registered.

Here's the function from our sample application that validates username and password and redirects to the two-factor authentication page if authy is enabled:

def create
  @user = User.find_by_email(params[:user][:email])

  if @user && @user.authenticate(params[:user][:password])
    # username and password is correct
    if(@user.authy_id != 0) #user is using two-factor
      Authy::API.request_sms(:id => @user.authy_id) # request the API to send and sms.

      # Rails sessions are tamper proof. We can store the ID and that the password was already validated
      session[:password_validated] = true
      session[:id] =
      redirect_to url_for(:controller => "sessions", :action => "two_factor_auth")
      flash[:notice] = "Successfully authenticated without two-factor"
      redirect_to @user
    flash[:error] = "Wrong username, password."
    @user =
    render 'new'

When the user wants to login, you use their e-mail (or whatever user identifier you are using) to locate their user profile in the database or directory. The authenticate function will check username and password and if the user has been Authy enabled. If so, redirect the user to the second page were they enter the token and complete the authentication. Here's the function for the second factor authentication:

def create_two_factor_auth
  @user = User.find(session[:id])
  token = params[:token]
  if @user && session[:password_validated] && @user.verify_token(token)
    @user.authy_used = true => false)
    session[:password_validated] = nil
    session[:id] = nil
    flash[:success] = "Securely signed in using Authy"
    redirect_to @user
    flash[:error] = "Wrong token"
    redirect_to new_session_path

Token verification involves sending the token and the id. Authy will respond HTTP status 200 if the token is correct.

def verify_token(token)
  token = Authy::API.verify(:id =>, :token => token)


The function simply passes the authy_id and the token the user entered. Then it check if the response is HTTP status 200, if so it returns true.

To prevent users account getting locked down, Authy won't check the tokens until we are certain the user has completed the registration process. If you want to verify token's anyway, you can pass ?force=true to verify.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more