Skip to content

Getting Started

Scope

The principle followed in this API is that all the complex work is handled in the Sinch Cloud, which means that service requests are used to handle all the elements of the authentication process:

  • Generate the One-Time Password (OTP)/PIN/Verification code (collectively called “tokens”)
  • Send the SMS or Email to the end-user that contains the message with the token
  • Send an SMS with a URL validation capability (one-step validation or two-step validation)
  • Validate the token, provided by the user.
  • Manage the creation, listing, validation of TOTP-compliant soft-tokens (such as generated by Google Authenticator and other soft-token apps) The service request definitions as well as the examples provided should be sufficient for developers to write applications to consume the API.

The following topics are not covered in this document: * How to set-up any Hardware or Landscape Proxies.

Message Definitions

The message body of requests in the current implementation will all be in JSON format - this means that you can’t user other formats, like XML body for the requests. For example, the definition in the spec of the Body for generating a new PIN is:

<accountId> ::= <Integer Literal>
<telephoneNumber> ::= <Integer Literal>
<messageBody> ::= <String Literal>
<characterSet> ::= <Boolean Literal>
<tokenLength> ::= <Integer Literal>
<pinType> ::= <Integer Literal>
<timeOut> ::= <Integer Literal>

The current service is a RESTful API implementation and JSON is preferred for this type of service. An example of the completed syntax is shown below:

Body:{
  "accountId": 550055,
  "telephoneNumber": "15712266022",
  “emailAddress” : “xyz.abc@Sinch.com”
  "messageBody": "This is your Token: [token]",
  "characterSet": "",
  "tokenLength": 4,
  "pinType": 0,
  "timeOut": 30
}
Property Description
accountId Company Account ID / MFA Account ID
telephoneNumber User Telephone number to receive TOKEN
emailAddress User E-Mail Address to receive TOKEN
messageBody Message that goes along with the TOKEN
tokenLength Size of PIN: min:4 , max:9
pinType Type of PIN: Numeric/Alphanumeric
timeOut Timeout of PIN: min:30sec, max:15min

Security

Sinch Authentication 365’s service will be delivered through HTTPS and will use oAuth 2.0 Token Authorization Framework conforming to IETF RFC-6749 to enable other applications to access the 2FA API with an Authorization token that needs to get refreshed over time in order to continue to allow the API to be accessed.

With this approach, the requests sent to the API doesn’t need to carry the user and password on every request and can only send the Bearer token to authorize the user through the requests.

For a Code Example, please see Section 9.1.2 and Subsequent topics after to check usage. The One-Time Password is generated using a SHA-256 algorithm based on HMAC with addition to TOTP and additional custom implementations to make it very secure and ensure it generates non-duplicated pins. Selecting the option to generate alphanumeric tokens also improves security.

Soft Token is based on the Google Authenticator which includes implementations of one-time passcode, that are generated using open standards developed by the Initiative for Open Authentication (OATH) (which is unrelated to OAuth). These implementations support the HMAC-Based One-time Password (HOTP) algorithm specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238.