2FA REST API

Overview

This page describes the resources that make up the 2FA REST API v1, for developers who want to integrate Two Factor Authentication into their application.

The 2FA REST API provides access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is JSON. Your method will be the standard HTTP method POST.

Authentication

HTTP Basic Authentication is used for all requests. If you access the API without having the correct credentials OR permission to access the API, you will get a HTTP 401 response.

We will provide you with a username and password to use. Your application username is the same as your application name on this page. If you don’t have these details, please contact optussd@modicagroup.com.

Base URI

All API access is over HTTPS, and accessed from: https://api.sms.optus.com.au/rest/2fa

Versions

The REST API version is currently v1. A custom media type is used to let consumers choose the data format they wish to receive:

Accept: application/vnd.modica.2fa.v1+json

Creating a Challenge

To send a challenge to a mobile handset, submit a POST request:

POST /challenges

{
  "destination": str:mobile-number
}

infoMobile number format must be international format e.g. +64211234567

To add a personalised message simply add the optional ‘content’ attribute:

{
  "content": "Your 2FA code is: %(code)s"
}

infoIf content is set you must include the %(code)s named variable otherwise an HTTP 400 is returned

To mask the source to a custom string, add the optional ‘mask’ attribute:

{
  "mask": "ModGrpExmpl"
}

infoMasking is not available for all countries and mobile carriers

infoThe maximum mask length is 11 characters. Masks exceeding this length will be rejected by mobile carriers

To modify the validity time for the 2FA code, add the optional ’expiresIn’ attribute:

{
	"expiresIn": "600"
}

infoIf “expiresIn” attribute is supplied, the 2fa code expiry time will be modified. The “expiresIn” is the number of seconds a code will remain active and valid. If the supplied “expiresIn” is shorter than 30 seconds or longer than 3600 seconds (1 hour) the challenge request will receive a 400 response.

infoIf not set, the default “expiresIn” value for a challenge code is 300 seconds (5 minutes).

On success:

HTTP/1.1 201 Created
X-Modica-Request-Id: uuid:request-id

{
  "created": str:timestamp,
  "expires": str:timestamp,
  "id": uuid:challenge-id
}

infoTimestamps are in UTC standard

infoCodes will expire 5 minutes after a challenge is created

On validation error:

HTTP/1.1 400 Bad Request
X-Modica-Request-Id: uuid:request-id
 
{
  "error": str:error-code
}

Challenge Response

To validate a response to a challenge submit a POST request:

POST /responses

{
  "challenge_id": uuid:challenge-id,
  "code": str:challenge-code
}

On success:

HTTP/1.1 201 Created
X-Modica-Request-Id: uuid:request-id

{
  "status": str:status-code
}

On validation error:

HTTP/1.1 400 Bad Request
X-Modica-Request-Id: uuid:request-id
 
{
  "error": str:error-code
}

Help

Having trouble integrating with any of our services? Contact optussd@modicagroup.com and we’ll help you sort it out.