Back to top

Veoo Two Factor Authentication API

This API provides PIN-based Two Factor Authentication over bulk SMS

PIN Flow

Request a PIN

Request a PIN
GET/request-pin

This endpoint will generate a PIN and send it to the specified msisdn over a bulk message route. The PIN will be stored by Veoo for the specified expiry time, and can be compared to a user-specified PIN by a follow-up request. All requests can have a validity period specified, which will cause prior 2FA attempts within the validity period to shortcut the PIN-send flow.

Example URI

GET https://2fa.veoo.com/request-pin
URI Parameters
HideShow
username
String (required) Example: client2FABulk

API Username associated with a bulk messaging account

password
String (required) Example: bulkpassword

API Password

source
String (required) Example: 2FAPIN

The msisdn (or alpha originator) that this message will appear to come from. The maximum length of a msisdn is 16 characters, where alpha originator has a max length of 11 characters. Special characters like white space and underscores are not recommended to use within originator text as we cannot guarantee delivery of these messages.

msisdn
String (required) Example: 447411000000

Must be formatted in international format. For example a UK msisdn would have the format 4477222333444.

message
String (optional) Default: Your PIN is {pin} Example: Heres your PIN: {pin}

A template for the PIN message. The string {pin} will be replaced by the generate PIN.

id
UUID (optional) Example: 12345

Your ID to be returned in delivery receipts for the PIN message.

expiry
Number (optional) Default: 86400 Example: 86400

How long the PIN will be valid for in seconds.

validity
string (optional) Default: 0 Example: 7 days, 86400, forever

How long since the last verified PIN for this msisdn to check for.

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "pin-sent",
  "messageId": "db9390cc-f199-4381-8872-6f9b52871e98"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "authorized",
  "lastAuth": "2016-03-18T11:51:12.000Z"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "error": "This route requires a valid bulk username and password"
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "error": "Internal API Error"
}

Verify a PIN

Verify a PIN
GET/verify-pin

This endpoint will compare the PIN passed with all PINs sent to this user that have not expired. PINs may be verified only once.

Example URI

GET https://2fa.veoo.com/verify-pin
URI Parameters
HideShow
username
String (required) Example: client2FABulk

API Username associated with a bulk messaging account

password
String (required) Example: bulkpassword

API Password

msisdn
String (required) Example: 447411000000
pin
Number (required) Example: 1234

The PIN entered by the user to be checked

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  status: 'incorrect',
  message: 'The PIN is not correct'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  status: 'expired',
  message: 'The PIN is no longer valid'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  status: 'ok',
  message: 'The PIN was correct and this user now authorized'
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "error": "This route requires a valid bulk username and password"
}

Last updated at 20 Mar 2018 08:03