SMS 2-Factor Authorization API

This is an API you can use to provide 2-factor authorization to your users. You register phone numbers with us, and when users want to log in, you POST an authorization request to our API endpoint. We then generate a random number and text it to the user. You can verify the user entered the correct input by sending a further POST request.

Integrations

We're currently working on integrations into popular web frameworks.

Documentation

Four steps to get started:

  1. Register a service (POST /api/services)
  2. Register phone numbers on that service (POST /api/{service-name}/phone)

    Then, when the user wants to log in:

  3. Send a validation code to the user's phone (POST /api/{service-name}/phone/authorize)

  4. Verify the user entered code and the 2-Factor generated code are identical (POST /api/{service-name}/phone/verify)

More details can be found on each specific page of the API.

Register a service

POST /api/services

Include the following values in the body of your POST request:

Possible responses

Register phone numbers for a service

POST /api/{service-name}/phone

Include the following value in the body of your POST request:

Possible responses

Authenticate the request using your service name and auth token. Most HTTP libraries have functions which allow you to do this easily. For example, in Python with the requests library:

import requests

service_name = "example"
service_token = "32b063cb637daa388e722cd223f6056b1"
phone_data = {
    "phone_number": "+12125551234"
}
requests.post("https://smsauth.herokuapp.com/api/example/phone",
              auth=(service_name, service_token), 
              data=phone_data)

Send a validation code

To send a validation code to a user's phone, make the following request:

POST /api/{service-name}/phone/authorize

Include the following values in your authenticated POST request:

Possible responses

Code Sample

Authenticate the request using your service name and auth token. Most HTTP libraries have functions which allow you to do this easily. For example, in Python with the requests library:

import requests

api_url = "https://smsauth.herokuapp.com"
service_name = "example"
service_token = "32b063cb637daa388e722cd223f6056b1"
phone_data = {
    "phone_number": "+12125551234"
}
response = requests.post(api_url + "/api/example/phone/authorize",
                         auth=(service_name, service_token), 
                         data=phone_data)
print response.content

Note

Each authorization request will be valid for only 10 minutes. You will not be able to generate more than 5 authorization tokens in a 10 minute period.

Verify a user-submitted code

To verify that a code submitted by a user on your site matches the code sent via text message to the user, send the following authenticated request:

POST /api/{service-name}/phone/verify

Include the following values with your post request:

Possible Responses

Note

To prohibit dictionary attacks, you will be limited to ten attempts per phone number in any ten-minute period.

Code Sample

Authenticate the request using your service name and auth token. Most HTTP libraries have functions which allow you to do this easily. For example, in Python with the requests library:

import requests

api_url = "https://smsauth.herokuapp.com"
service_name = "example"
service_token = "32b063cb637daa388e722cd223f6056b1"
# Let's say you just received a verification code of 555555
verification_code = "555555"
phone_data = {
    "phone_number": "+12125551234",
    "verification_code": verification_code
}
response = requests.post(api_url + "/api/example/phone/verify",
                         auth=(service_name, service_token), 
                         data=phone_data)
print response.content