Introduction

<aside> 💡 This guide represents the OnlyAuth embeddable widget, which is exceptionally useful as a drop-in replacement for current 2FA, or in addition if you are not doing any 2FA today.

</aside>

<aside> <img src="/icons/info-alternate_purple.svg" alt="/icons/info-alternate_purple.svg" width="40px" /> We are currently working on React components for better programmability and customizability. Email us at [email protected] if you would like to participate in the beta.

</aside>

Vocabulary and Flows

<aside> ❗ You need to have an OnlyAuth account, which will provide you with your API credentials. Please sign up at https://app.onlyauth.io/ if you do not have an account.

</aside>

Terms

First let’s introduce the words you will encounter while building and using the OnlyAuth 2FA Platform.

Client SDKs

We support the following SDKs:

• Python
• PHP
• Javascript (server-side)

We are actively releasing new ones frequently, just let us know if you have a request.

Flow

The OnlyAuth Widget is a lightweight SDK that you will insert into your website to allow customers to pick, and then authenticate, via their chosen 2FA/MFA method(s). Since the OnlyAuth Client lives in on the client-side, you will need to use your backend to connect to the OnlyAuth’s API for security. A flow will look something like this:

<aside> 💡 In the first version the OnlyAuth widget is an embeddable iframe. If you would rather work with a React component, let us know at [email protected].

</aside>

Step 1: Use your App Server to obtain an access token

When initializing the Widget, you need to begin by using your backend. Remember, the Client is a client-side application and savvy users can inspect (and potentially change) any information. For this reason, we will be using your app server to create a JWT, which will then be used to send to the Widget. Sample Python code (without the SDK) is as follows:

import requests

url = "<https://api.onlyauth.io/server/access-tokens/new>"

payload = 'redirect_uri=http%3A%2F%2Fexample.com&language=en-us&end_user_phone_number=%2B14155555555&app_id=APPX-3582f876-b145-45a9-986c-f2a&end_user_uuid=101&region=us-1&client_id=CLNT-841305dd-d7de-420d-8b6c-371acbfedd36'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Authorization': 'Bearer 2b50c34x24a192dee3ed52a8e20392de9edfc780ac99'
}

response = requests.request("POST", url, headers=headers, data=payload)

jwt = response.json().get('token')

See the full API endpoint spec here.

Note the end_user_phone_number is really important as this represents the phone number of the user you’re trying to authenticate. Please be aware that if your account is in SANDBOX MODE then different behaviors will happen (see below section for more information).

Step 2: Add the OnlyAuth Widget

After the user has inputted their username and password (email, or whatever you collect), and before you take them to their private account area, you’ll want to add to the OnlyAuth widget here. Once the user has fully authenticated, the widget will redirect them to the specified redirect_uri with a seperate token (success token) appended to the URL.

Now for the code to add the widget to your client-side:

 <!-- OnlyAuth Widget Integration -->
   <div class="onlyAuthWrapper"
      style="position: relative; padding-bottom: 75%; padding-top: 25px; height: 0; overflow: hidden;">

     <iframe src="<https://api.onlyauth.io/client/?token=>{{ token }}&app_id={{ app_id }}" allowfullscreen
           style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"></iframe>
      </div>
 <!-- End OnlyAuth integration -->

You will want to replace the {{ token }} variable with the JWT you generated in the previous step. And the app_id here represents your application.

Step 3: The Magical Part

In Step 3 this is where the magic happens with OnlyAuth. Based on your configured settings, your users will perform their Two-Factor Authentication, or even Multi-Factor Authentication if you have turned it on.

Step 4: Validate the success token

Once the user has completed their authentication, the OnlyAuth Widget will redirect the user to the redirect_uri that you have specified in Step 1. It will also add ‘token=success_token’ to the end of this value. So if you have a standard page with no URL parameters already, be sure to add a ? at the end, and likewise if you already have URL parameters, be sure your redirect_uri ends with an &.

Examples of good redirect_uris:

• https:///www.example.com/myaccount?
• https://www.mycompany.com/account?analytics=123&othersuperparam=value&
• https://myco.com/account.php?

You can validate the success token by making a simple GET request to the endpoint. If you get a 200 and validate that the "end_user_uuid" is the same, then you are all set to grant access!

Success token API endpoint definition

<aside> ⚠️ By default the success token will expire after 30 seconds. We suggest using a very low TTL, as it should only be used once for you to set your cookies/other information that identifies that your user has successfully completed the login process.

</aside>

Rate Limits

Rate-limited requests will return a "rate_limited" error code (HTTP response status 429). Some bursts beyond the average rate are allowed.

<aside> ❗ Rate limits may change

Rate limits are always subject to change. If you require an increase, please contact support with the requested amount and an explanation of your use case.

</aside>

Error Codes

Error responses contain more detail about the error in the response body, in the "errors" and "message"properties.

Entities

All identificators in the OnlyAuth ecosystem are uuids, with a 4 letter prefix.

OnlyAuth Application Configuration

Below are all of the listed parameters on an application. We are currently working on exposing these via an API, so in the meantime please contact us to make any changes.

Supported Parameters

Note: This requires explicit permission from OnlyAuth to be disabled, and the process may take a few days to ensure the security and safety of the platform for the end-users. | True | True/False | | backup_codes_enrollment | Force user to save backup codes in lieu of 2FA channel for emergency situations. Note: This is a forward-looking parameter, and today does not change the behavior. | False | True/False | | success_token_ttl | The time-to-live for the success_token after a user has completed authentication.

In seconds | 30 | Any number up to 3,600 | | success_token_onetime | Whether to allow the success_token to be used only one-time

Note: We will do our best effort to ensure only one-time use, however on rare occasions multiple-uses may be permitted | False | True/False | | defer_sms_usage | Suggest to the end-user more secure, less error-proned channels before they can send the OTP code via SMS Note: This is a forward-looking parameter, and today does not change the behavior. | True | True/False | | mfa_enabled | Whether to allow the end-user to enable Multi-Factor Authentication on your application. Note: This is a forward-looking parameter, and today does not change the behavior. | True | True/False | | mfa_enforced | Force the user to use MFA on your application. Requires mfa_enabled to be set to true before setting. Note: This is a forward-looking parameter, and today does not change the behavior. | False | True/False | | intelligent_2fa | Use ML and other advance signals to allow the end-user to bypass 2FA on certain circumstances Note: This is a forward-looking parameter, and today does not change the behavior. | False | True/False | | auto_enroll_new_channels | Whether to auto-enable new 2FA channels (note these will always be free channels, paid channels will require explicit enrollment) Note: This is a forward-looking parameter, and today does not change the behavior. | True | True/False |

What is the Sandbox Mode?

Sandbox Mode is what you see on the Demo, it is the default setting for all applications. The security and safety for the users of the OnlyAuth Platform is by far the most important thing. So all developers accounts must go thorough a review prior to being able to exit the sandbox. The sandbox is meant for you to get through all of the implementation in a dev environment before going to production.

There are several key behavior differences while in sandbox mode:

• More strict and lower API limits. Especially low rate limits around action creation
• SMS mode and all paid channels are disabled. The API will return an OTP code instead of actually sending the SMS
• The widget does not actually redirect to redirect_uri unless configured to do so (the widget will display an occasional warning saying it is in sandbox mode)
• Even if a phone number exists on the OnlyAuth platform, unless you have used it to authenticate against your sandbox app, it will appear to be unregistered and not having the mobile app installed. In other words, you will always have a very different view on the world of user statuses

SMS as a 2FA Channel

Currently SMS is available by request only. Please contact us for more information.

API Endpoints

Endpoints

Appendix: OnlyAuth Widget States

Initializing

This is the state in which the widget checks the validity of the JWT token, and sees the status of the user. Generally this will last only a second or less.

User does not have the OnlyAuth Mobile App