Documentation

From the Demo to a Real World Implementation

Now that you understand the basics of the API, let's see it in action.

Walk through the basic functions with a demo

We package a demo with each of our language libraries. Our demo is meant to be simple and self-contained. As such, the demo contains all the necessary actions. Toopher revolves around pairing a device then authenticating actions with that device. Both actions are accomplished via our API. Let's walk through the demo to get familiar with the basic Toopher functions.

In practice, you will need to move the actions into their logical location on your server, which we discuss more in the next section.

We initiate our demo by simply running the script; for example, python demo.py for our Python library. The first you will do is input your key and secret. Your key and secret are unique and are provided to you when you create a requester. This creates an API object that can issue pairing and authentication requests.

With an API object set up, we move to pairing. Pairing requires a pairing phrase and username. In general, you can use the client's site username. Pairing ends whenever the user accepts the pairing on their phone.

After pairing, we can issue authentication requests for users. Authentication requests require a pairing id and a terminal name, with an optional action parameter. The standard action is "login", but you could enable Toopher on whatever action you desire. Authentication ends whenever the user accepts the action on their phone.

That's it! The Toopher Two Step simply pairs a user's phone with your service, then makes authentication requests that must be accepted on the user's phone.

From demo to real world

The demo provides an introduction to Toopher and our APIs furnish all necessary functionality. Enabling Toopher for your service should be straightforward, but there are several steps.

Steps to enable Toopher on your site

Determine if user is Toopher enabled

Allow user to pair

Authorize user logins

Allow user to reset Toopher

Easy enough, but what does that look like in my web application?

Example of how to enable Toopher on your site

Determine if user is Toopher enabled

You will need to track if users have already paired with Toopher. We recommend augmenting the User object (or database table) with Toopher information, including pairing_id.

Allow user to pair

Create an user interface element for the pairing phrase

Create an API endpoint that initiates a user-phone pairing

Create an API endpoint that checks the status of a pairing request

Once the user has accepted the pairing request, update their account with the Toopher information

Create a visual indicator to tell the user what's happening; for example, "Pairing. Please accept the request from Toopher on your phone."

Rather than wait on the server-side, we recommend you use JavaScript to wait on the user. Note: Consider adding a timeout. We suggest two minutes.

Allow the user to unpair

Create a user interface element to remove Toopher from the account

Create an API endpoint that removes the user's Toopher pairing ID from their account

Link the interface element to your newly created unpair function

Authorize user logins

When a user initiates an authentication, check if they have a Toopher pairing ID; if they do, authenticate with Toopher.

Name the user's computer

Create a user interface element to accept the computer name

Create an API endpoint that stores the user's computer name

Create an API endpoint that initiates an authentication request

Create an API endpoint that checks the status of an authentication request

Timeout - Rather than wait on the server-side, we recommend you use JavaScript to wait on the user.

Visual indicator about what's happening

Allow user to reset Toopher

This is a vital step in account recovery. Resetting Toopher could be done by contacting your support center or in the same manner that a user would reset passwords.

Next Up

With a basic implementation in place, be sure to allow users to recover their account if, for example, they lost their mobile device.