Skip to content

Soft Token

A soft token is a mobile app, such as Google Authenticator that will provide a code adhering to the TOTP standard. End users may then enter that code as part of a two-step verification process. APIs are provided to generate the secret key as well as the QR code and to validate a user-entered code.

The process is outlined in the diagram, below:

soft_tokens_image_1

1. Soft Token Registration

This section defines the structure and content of the soft token generation and register request and response.

<Soft Token Registration Request> ::= 
<CLIENT ID> ::= <LONG Literal>
<USER ID> ::= <STRING Literal>

Where:

Property Description
Account ID Is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal
USER ID Could be user’s telephone number, email-id, name

For given client and user id combination a soft token key and QR code will be generated and will be saved in database in soft token table with token status 1 which is active status. Soft token key and QR code will be returned in response and will be sent to user only once.

<Soft Token Registration Response> ::=
<isSuccess> ::= <Boolean Literal>
<Message>  ::= <String Literal>
<SOFT TOKEN> ::= <String Literal>
<QR CODE> ::= <String Literal>

Where:

Property Description
isSuccess Is Status of the call if it was success.
Message Is the message status for the request.
SOFT TOKEN Is the generated soft token key.
QR CODE Is the generated soft token QR code.

Content-Type: application/json
Authorization: <token type> <oAuth token>

Body

{
    "clientId":<MFA Account_ID>,
    "userId": <user’s email id or mobile number or name>
}

Response

{
    "clientId":<MFA Account_ID>,
    "clientName": null,
    "userId": <user’s email id or mobile number or name>,
    "secretKey": 0,
    "softToken": <Generated code>,
    "softTokenQRCode": <Generated QR url>,
    "message": null, [in case of success],
    "success": <status>
}

2 Validate Soft Token

This section defines the structure and content of the Soft Token Validation request and response.

<Soft Token Validation Request> ::= 
<CLIENT ID> ::= <LONG Literal>
<USER ID> ::= <STRING Literal>
<SECRET KEY> ::= <INTEGER Literal>
Where:

Property Description
Account ID Is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
USER ID Could be user’s telephone number, email-id, name.
Secret Key Is the key generated by Google Authenticator (or another TOTP-compliant soft token generator).
<Soft Token Validation Response> ::=
<SUCCESS> ::= <Boolean Literal>
<Message>  ::= <String Literal>

Where:

Property Description
isSuccess is Status of the call if it was success.
Message is the message status for the request

Header

Content-Type: application/json
Authorization: <token type> <oAuth token>

Body

{
    "clientId":<MFA Account_ID>,
    "userId": <user’s email id or mobile number or name>,
    "secretKey: <Secret key>                              
}

Response

{
    "success": <Status>,
    "message": <Message>,
}

3. Deactivate Soft Token

This section defines the structure and content of the Soft Token Deactivation request and response.

<Soft Token Deactivation Request> ::= 
<CLIENT ID> ::= <LONG Literal>
<USER ID> ::= <STRING Literal>
Where:

Property Description
Account ID Is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
USER ID Could be user’s telephone number, email-id, name.
<Soft Token Deactivation Response> ::=
<SUCCESS> ::= <Boolean Literal>
<Message>  ::= <String Literal>

Where:

Property Description
isSuccess is Status of the call if it was success.
Message is the message status for the request

Header

Content-Type: application/json
Authorization: <token type> <oAuth token>

Body

{
    "clientId":<MFA Account_ID>,
    "userId": <user’s email id or mobile number or name>
}

Response

{
    "success": <Status>,
    "message": <Message>,
}

4. List Soft Token

This section defines the structure and content of the Soft Token List request and response.

<Soft Token List Request> ::= 
<CLIENT ID> ::= <LONG Literal>

Where:

Property Description
Account ID is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
<Soft Token List Response> ::=
<SUCCESS> ::= <Boolean Literal>
<Message>  ::= <String Literal>
<CLIENT ID> ::= <Long Literal>
<USER ID> ::= <String Literal>
<CREATION DATE> ::= <Timestamp>
<RETRY COUNT> ::= <Integer Literal>

Where:

Property Description
isSuccess Is Status of the call if it was success
Message Is the message status for the request.
Client Id Is MFA account id.
User ID Is the register user id for that client id
Creation Date Is date of soft token registration.
Retry count Type of PIN: Numeric/Alphanumeric
timeOut Is maximum retry count for that client in case of validation failure

Header

Content-Type: application/json
Authorization: <token type> <oAuth token>

Body

{
    "clientId":<MFA Account_ID>,
}       

Response

{
    "softTokenList": [
    {
        "rowId": null,
        "createdDate": <Timestamp>,
        "clientId": <MFA Client ID>,
        "userId": <User Id>,
        "softTokenKey": null,
        "qrCode": null,
        "tokenStatus": 0,
        "retryCount": 0,
        "lockPeriod": null,
        "maxRetry": <max retry available>
    },
    {
        "rowId": null,
        "createdDate": <Timestamp>,
        "clientId": <MFA Client ID>,
        "userId": <User Id>,
        "softTokenKey": null,
        "qrCode": null,
        "tokenStatus": 0,
        "retryCount": 0,
        "lockPeriod": null,
        "maxRetry": <max retry available>
    }
    ],
    "message": "Success",
    "success": true
}