Skip to content

Token Management

1. PIN/Verification Code/OTP (e.g. token) Generation

This section defines the structure and content of the Sinch Authentication 365 token Generation and SMS Send calls with the generated token method.

<Auth365 OTP Generation Request> ::= 
<Account ID> ::= <Integer Literal>
<Phone Number> ::= <Integer Literal>
<Email address> ::= <String Literal>
<Secondary key> ::= <String Literal>
<Message Body> ::= <String Literal>
<Character Set> ::= <String Literal>
<Token Length> ::= <Integer Literal>
<Pin Type> ::= <Integer Literal>
<Timeout> ::= <Integer Literal>

Where:

  • Account ID - is the system Account that will have access to send messages through the HUB Account ID This is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
  • Phone Number - is the user telephone number that will receive the token.
  • E-Mail Address - is the user E-Mail address that will receive the token.
  • Secondary Key - is the secondary key (or secondary identifier) which will be attached to the Phone number or E-Mail Address while generating the token.
  • Message Body - is the message that will be carried over with the token.
  • Character Set - is the message Character Set.
Character Set
8b
BIG5
UTF8
GB2312
8859-7
BIG5 and UCS2
  • Token Length - is the Length of the Character from Minimum 4 to a Maximum of 9.
  • Pin Type - is the type of Pin 0 for Numeric and 1 for Alphanumeric.
  • Timeout - is how long the generated token will be valid in seconds. Minimum of 30 to a Maximum of 900.

<Auth365 OTP Generation Response> ::=
<Status> ::= <String Literal>
<Message>  ::= <String Literal>
<Order ID> ::= <Integer Literal>
<Token> ::= <String Literal>
Where:

  • Status - status of the call if it was success.
  • Message - is the message status for the request with the generated PIN if successful.
    For example: Your generated Pin is [token]
    <Message> ::= [token]
  • Order ID - is the generated A2P order ids, for tracking the SMS status.

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

Body

{
    "accountId": <MFA Account_ID>,
    "telephoneNumber": "<phone_number>",         *mandatory, either send this or the email address
    "emailAddress" : "<email address>",          *mandatory, either send this or the msisdn
    "messageBody": "<messagebody \[token]>",     *optional
    "characterSet": "\[]",                       *optional
    "tokenLength": 4,                            *optional
    "pinType": 0,                                *optional
    "timeOut": 30,                               *optional
    "secondaryKey": "<secondary key>"            *optional 
}

Response

{
    "status": "<Status>",
    "message": "<Message>",
    "token"  : "<Token>",                 *generated in case if account is not using Sinch Authentication 365 Hubs
    "orderID": <Order ID>
}

2. Two Part PIN/Verification Code/OTP (e.g. token) Generation

Background: This is an optional feature that will provide the ability to generate a TWO-PART token. This feature provides extra security. For this feature, the regular PIN or Verification code and a special alphanumeric code (4 random characters) are generated.

This 4-character alphanumeric code will be returned to the application in the API, meaning the customer’s application could display that code on their website AND in the SMS message along with the regular PIN code. That way, the user can visually match the code in their SMS with the code displayed on the website. Only the regular PIN code is validated as is the normal method.

The options include ability to generate and insert both codes into the SMS message and have the 4-character code returned in the API. If users generate multiple codes, they can use the currently displayed 4-character code on the website to match the PIN code they received in the SMS message as the proper one to be validated.

This can also help users validate that the incoming SMS message is, in fact, from their bank or financial institution. They will expect to receive an SMS message with the appropriate 4-character code along with their PIN code.

Note

Only the 2nd part of the 2-part validation code generated is used for validation. The first part (the 4-character alphanumeric code), is not part of the validation. It is mainly used as a visual reference for the end user.

This section defines the structure and content of the Sinch Authentication 365 2-Part token Generation and SMS Send calls with the generated token method.

<Auth365 OTP Generation Request> ::= 
<Account ID> ::= <Integer Literal>
<Phone Number> ::= <Integer Literal>
<Email address> ::= <String Literal>
<Secondary key> ::= <String Literal>
<Message Body> ::= <String Literal>
<Character Set> ::= <String Literal>
<Token Length> ::= <Integer Literal>
<Pin Type> ::= <Integer Literal>
<Timeout> ::= <Integer Literal>

Where:

  • Account ID is the system Account that will have access to send messages through the HUB Account ID This is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
  • Phone Number is the user telephone number that will receive the token.
  • E-Mail Address is the user E-Mail address that will receive the token.
  • Secondary Key is the secondary key (or secondary identifier) which will be attached to the Phone number or E-Mail Address while generating the token.
  • Message Body is the message that will be carried over with the token.
    • As the token is a 2-part token, you can specify "[token]" in the text, which will be replaced with the full 2-part token: wxyz-123456.
    • You may also split the first part of the 2-part token (the alphanumeric part) by using the designation: "[token-part1]" and the actual verification code as "[token-part2]."
    • Example 1: Your validation code is: [token] will be delivered as:
      • Your validation code is: WXYZ-123456 /
    • Example 2: Your validation code information: [token-part1] and [token-part2].
      • Your validation code information: WXYZ and 123456
  • Character Set is the message Character Set
Character Set
8b
BIG5
UTF8
GB2312
8859-7
BIG5 and UCS2
  • Token Length - is the Length of the Character from Minimum 4 to a Maximum of 9.
  • Pin Type - is the type of Pin 0 for Numeric and 1 for Alphanumeric.
  • Timeout - is how long the generated token will be valid in seconds. Minimum of 30 to a Maximum of 900.
    <Auth365 OTP Generation Response> ::=
    <Status> ::= <String Literal>
    <Message>  ::= <String Literal>
    <Order ID> ::= <Integer Literal>
    <Token> ::= <String Literal>
    

Where:

  • Status - status of the call if it was success.
  • Message - is the message status for the request with the generated PIN if successful. For example: Your generated Pin is [token]
    <Message> ::= [token]
  • Order ID - is the generated A2P order ids, for tracking the SMS status.

Header

Note the additional element of the header: "2-Part" – must be set to true, if you want the 2-part token generated.
Content-Type: application/json
Authorization: <token type> <oAuth token>
2-Part: true (Mandatory for 2-part token generation)

Body

{
    "accountId": <MFA Account_ID>,
    "telephoneNumber": "<phone_number>",         *mandatory, either send this or the email address
    "emailAddress" : "<email address>",            *mandatory, either send this or the MSISDN (phone number)
    "messageBody": "<messagebody \[token]>",     *Can also use: [token-part1] and [token-part2]
    "characterSet": "\[]",                       *optional
    "tokenLength": 4,                            *optional
    "pinType": 0,                                *optional
    "timeOut": 30,                                *optional
    "secondaryKey": "<secondary key>"                                *optional 
}

Response

{
    "status": <Status>,
    "message": <Message>,
    "token"  : <Token>,    *generated in case if account is not using Sinch Authentication 365 Messaging Hubs
    "orderID": <Order ID>,
    "part2Token": <Part Two Token> 
}

3. Voice PIN Code/OTP Generation

Background: This is an optional feature that will provide the ability to generate a token and deliver it as voice instead of SMS.

This has the same structure as the SMS token generation, only diffirence there is an extra header
voice: true

Header

Content-Type: application/json
Authorization: <token type> <oAuth token>
2-Part: true (Mandatory for 2-part token generation)
voice: true

Body

{
    "accountId": <MFA Account_ID>,
    "telephoneNumber": "<phone_number>",         *mandatory, phone number which will receive the call
    "messageBody": "<messagebody \[token]>",     *Can also use: [token-part1] and [token-part2]
    "characterSet": "\[]",                       *optional
    "tokenLength": 4,                            *optional
    "pinType": 0,                                *optional
    "timeOut": 30,                                *optional
    "secondaryKey": "<secondary key>"                                *optional 
}

Response

{
    "status": <Status>,
    "message": <Message>,
    "token"  : <Token>,    *generated in case if account is not using Sinch Authentication 365 Messaging Hubs
    "orderID": <Order ID>,
    "part2Token": <Part Two Token> 
}

4. PIN/Verification Code/OTP (e.g. token) Generation VIA GENERIC KEY ENDPOINT

This section defines the structure and content of the Sinch Authentication 365 token Generation and SMS Send calls with the generated token method.

<Auth365 OTP Generation Request> ::= 
<Account ID> ::= <Integer Literal>
<Key> ::= <String Literal>
<Secondary key> ::= <String Literal>
<Message Body> ::= <String Literal>
<Character Set> ::= <String Literal>
<Token Length> ::= <Integer Literal>
<Pin Type> ::= <Integer Literal>
<Timeout> ::= <Integer Literal>

Where:

  • Account ID - is the system Account that will have access to send messages through the HUB Account ID This is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
  • Key - is the generic key (any string) that can be used as a recipient address.
  • Secondary Key - is the secondary key which will be attached to the Key while generating the token.
  • Message Body - is the message that will be carried over with the token.
  • Character Set - is the message Character Set.
Character Set
8b
BIG5
UTF8
GB2312
8859-7
BIG5 and UCS2
  • Token Length - is the Length of the Character from Minimum 4 to a Maximum of 9.
  • Pin Type - is the type of Pin 0 for Numeric and 1 for Alphanumeric.
  • Timeout - is how long the generated token will be valid in seconds. Minimum of 30 to a Maximum of 900.

<Auth365 OTP Generation Response> ::=
<Status> ::= <String Literal>
<Message>  ::= <String Literal>
<Order ID> ::= <Integer Literal>
<Token> ::= <String Literal>
Where:

  • Status of the call if it was success.
  • Message is the message status for the request with the generated PIN if successful.
    For example: Your generated Pin is [token]
    <Message> ::= [token]
  • Order ID is the generated A2P order ids, for tracking the SMS status.

Header

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

Body

{
    "accountId": <MFA Account_ID>,
    "key" : <generic key>,                       *mandatory, either send this or the msisdn
    "messageBody": "<messagebody \[token]>",     *optional
    "characterSet": "\[]",                       *optional
    "tokenLength": 4,                            *optional
    "pinType": 0,                                *optional
    "timeOut": 30,                    ,          *optional
    "secondaryKey": "<secondary key>"            *optional 
}

Response

{
    "status": <Status>,
    "message": <Message>,
    "token"  : <Token>,                *generated in case if account is not using Sinch Authentication 365 Hubs
    "orderID": <Order ID>
}

5. Token Validation

This section provides definitions of the structure and content of the Sinch Authentication 365 token Validation of a sent SMS token method.

<Auth365 OTP Validation Request> ::= 
<Account ID> ::= <Integer Literal>
<Phone Number> ::= <String Literal>
<One Time Password> ::= <String Literal>
<Secondary Key> ::= <String Literal>
Where:

  • Account ID - is the system Account that will have access to send messages through the HUB Account ID.
  • Phone Number - is the user telephone number that will receive the token password or the email-address which was used for token generation. This can also refer to the generic key that was entered which using the /tokens/generateByKey endpoint.
  • One Time Password - is the [token] that was generated and sent to the Mobile handset as an SMS (or email). If a 2-part token was generated, this is only the 2nd-part for the two elements that were generated.
  • Secondary Key - is the secondary key which will be attached to the Phone Number key. This refers to any secondary key which was used while generating the token.

<Auth365 OTP Validation Response> ::=
<Status> ::= <String Literal>
<Message>  ::= <String Literal>
Where: * Status - Status of the call if it was success or error.
Message status* - for the request with the generated PIN if successfully authenticated. If error will output the message error code.

Header

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

Body

{
    "accountId":<Mfa Account ID>,
    "telephoneNumber": <msisdn> or <email address> or <generic key>,
    "oneTimePassword": <Token>,
    "seconarykey": <secondary key>
}

Response

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

6 URL Validation

This section defines the structure and content of the Sinch Authentication 365 URL Validation option (one-step validation). For details of the Account Setup fields and default setting, refer the Section 1, on page 4.

For Header:

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

For Body:

<Auth365 OTP Generation Request> ::= 
<Account ID> ::= <Integer Literal>
<Phone Number> ::= <Integer Literal>
<Email address> ::= <String Literal>
<Secondary key> ::= <String Literal>
<Success Message> ::= <String Literal>
<Character Set> ::= <String Literal>
<Token Length> ::= <Integer Literal>
<Pin Type> ::= <Integer Literal>
<Timeout> ::= <Integer Literal>
<Headline> ::= <String Literal>
<Subhead> ::= <String Literal>
<Message Body> ::= <String Literal>

Where: * Account ID - is the system Account that will have access to send messages through the HUB Account ID This is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
Phone Number - is the user telephone number that will receive the token.
E-Mail Address - is the user E-Mail address that will receive the token.
Secondary Key - is the secondary key (or secondary identifier) which will be attached to the Phone number or E-Mail Address while generating the token.
Success Message - is the message that will be displayed on the page when the user clicks on the URL.
Character Set* - is the message Character Set.

Character Set
8b
BIG5
UTF8
GB2312
8859-7
BIG5 and UCS2
  • Token Length - is the Length of the Character from Minimum 4 to a Maximum of 9.
  • Pin Type - is the type of Pin 0 for Numeric and 1 for Alphanumeric.
  • Timeout - is how long the generated token will be valid in seconds. Minimum of 30 to a Maximum of 900.
  • Headline - as per client requirement for landing page (see examples).
  • Subhead - as per client requirement for landing page.
  • Message Body - String message user wants to send along with URL.

For Response:

<Auth365 OTP Generation Response> ::=
<Status> ::= <String Literal>
<Message>  ::= <String Literal>
<Order ID> ::= <Integer Literal>
<Token> ::= <String Literal>

Where: * Status - of the call if it was success.
Message* - is the message status for the request with the generated PIN if successful.

For example: Your generated Pin is [token]
<Message> ::= [token]

  • Order ID - is the generated A2P order ids, for tracking the SMS status.

Header

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

Body

{
"accountId": <MFA Account_ID>,
"telephoneNumber": "<phone_number>",                     *mandatory, either send this or the email address
"emailAddress" : "<email address>",                        *mandatory, either send this or the MSISDN
"successmsg": "<success message>",                        *optional
"characterSet": "\[]",                                    *optional
"tokenLength": 4,                                         *optional
"pinType": 0,                                             *optional
"timeOut": 30                                             *optional
"secondaryKey": "<secondary key>",                        *optional 
"headline": "<headline>",                                 *optional
"subhead": "<subhead>",                                   *optional
"acceptMsg" :  "<acceptMsg>",                             *optional
"declineMsg" : "<declineMsg>",                            *optional
"affirmativeButtonText" : "<affirmativeButtonText>",      *optional
"declineButtonText" : "<declineButtonText>",              *optional
"mainText" : "<mainText>"                                 *optional
}

Response

Asynchronous Request

The API will reply with a direct response in the HTTP Call with the ID of the request in process, this response is only for sending the URL acceptance and status and not the actual user authorization.

{
    "status": <Status>,
    "message": <Message>,
    "token"  : <Token>,    *generated in case if account is not using Sinch Authentication 365 Hubs
    "orderID": <Order ID>,
    "id": <id>
}

Asynchronous Request Callback

When the URL is Validated by end user, it will trigger a callback to the registered "Callback URL" defined on the Administrative Dashboard UI: Accounts page with the following format;

{
    "status": <Status>, 
    "id":     <id>,
    "message": <Message>
}

Asynchronous Request Callback Signature

To trust the source of the message you can configure a Signature Secret on the Administrative Dashboard UI: Accounts page which is used to hash the body of the message with the "HMAC 256" algorithm and sent in the x-Sinch-di-signature header. For every received hash, you should rehash the body with the stored Secret to match the signature validation when the callback is received.

{
    "status": <Status>,
    "id":     <id>,
    "message": <Message>
}

7 2-Step URL Validation

This section defines the structure and content of the Sinch Authentication 365 for 2-step URL Validation. In this form of authorization, when user clicks on URL it redirects user to a landing page whereby the user may accept or decline the validation.

For details of the Account Setup fields and default setting, refer the Section 3, starting on page 4.

Header

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

<Auth365 OTP Generation Request> ::= 
<Account ID> ::= <Integer Literal>
<Phone Number> ::= <Integer Literal>
<Email address> ::= <String Literal>
<Secondary key> ::= <String Literal>
<Success Message> ::= <String Literal>
<Character Set> ::= <String Literal>
<Token Length> ::= <Integer Literal>
<Pin Type> ::= <Integer Literal>
<Timeout> ::= <Integer Literal>
<Headline> ::= <String Literal>
<Subhead> ::= <String Literal>
<Message Body> ::= <String Literal>
<Affirmative Button Text> ::= <String Literal>
<Decline Button Text> ::= <String Literal>
<Accept Msg> ::= <String Literal>
<Decline Msg>  ::= <String Literal>
<Main Text> ::= <String Literal>
<Button Background Color> ::= <String Literal>
  • Account ID is the system Account that will have access to send messages through the HUB Account ID This is the MFA Account ID, which can be found on the Account Info page of Sinch Authentication 365 portal.
  • Phone Number is the user telephone number that will receive the token
  • E-Mail Address is the user E-Mail address that will receive the token.
  • Secondary Key is the secondary key (or secondary identifier) which will be attached to the Phone number or E-Mail Address while generating the token.
  • Success Message is the message that will be displayed on the page when the user clicks on the URL.
  • Character Set is the message Character Set
Character Set
8b
BIG5
UTF8
GB2312
8859-7
BIG5 and UCS2
  • Token Length - is the Length of the Character from Minimum 4 to a Maximum of 9.
  • Pin Type - is the type of Pin 0 for Numeric and 1 for Alphanumeric.
  • Timeout - is how long the generated token will be valid in seconds. Minimum of 30 to a Maximum of 900.
  • Headline - as per client requirement for the landing page.
  • Subhead - as per client requirement for the landing page.
  • Message Body - String message user wants to send along with URL.
  • Affirmative button text - is the text user wants on affirmative button.
  • Decline button text is the text user wants on decline button.
  • Accept Message - is the message which will be displayed on final landing page when user clicks on affirmative button.
  • Decline Message - is the message which will be displayed on final landing page when user clicks on decline button.
  • Main text - is the text user wants to see on the landing page.
  • Button Background Color - is the color user wants to set for both affirm and decline button.

Response

<Auth365 OTP Generation Response> ::=
<Status> ::= <String Literal>
<Message>  ::= <String Literal>
<Order ID> ::= <Integer Literal>
<id> ::= <Integer Literal>
<Token> ::= <String Literal>

Where:

  • Status - Status of the call if it was success.
  • Message - is the message status for the request with the generated PIN if successful.
    For example: Your generated Pin is [token]
    <Message> ::= [token]
  • Order ID - is the generated A2P Messaging order ids, for tracking the SMS status.

Header

Content-Type: application/json Authorization: Async : Is2Step :

Body

{
"accountId": <MFA Account_ID>,
"telephoneNumber": "<phone_number>",                     *mandatory, either send this or the email address
"emailAddress" : <email address>,                        *mandatory, either send this or the msisdn
"successmsg": "<success message>",                        *optional
"characterSet": "\[]",                                    *optional
"tokenLength": 4,                                         *optional
"pinType": 0,                                             *optional
"timeOut": 30                                             *optional
"secondaryKey": "<secondary key>",                        *optional 
"headline": "<headline>",                                 *optional
"subhead": "<subhead>",                                   *optional
"acceptMsg" :  "<acceptMsg>",                             *optional
"declineMsg" : "<declineMsg>",                            *optional
"affirmativeButtonText" : "<affirmativeButtonText>",      *optional
"declineButtonText" : "<declineButtonText>",              *optional
"mainText" : "<mainText>"                                 *optional
}

Response

Asynchronous Request

The API will reply with a direct response in the HTTP Call with the ID of the request in process, this response is only for sending the URL acceptance and status and not the actual user authorization.

{
"status": <Status>,
"message": <Message>,
"id":     <id>,
"token"  : <Token>    *generated in case if account is not using Sinch Authentication 365 Hubs
"orderID": <Order ID>
}

Asynchronous Request Callback

When the URL is Validated by end user, it will trigger a callback to the registered "Callback URL" defined on the Administrative Dashboard UI: Accounts page with the following format;

{
"status": <Status>,
"message": <Message>,
"id":     <id>
}

Asynchronous Request Callback Signature

To trust the source of the message you can configure a Signature Secret on the Administrative Dashboard UI: Accounts page which is used to hash the body of the message with the "HMAC 256" algorithm and sent in the x-Sinch-di-signature header. For every received hash, you should rehash the body with the stored Secret to match the signature validation when the callback is received.

{
"status": <Status>,
"message": <Message>,
"id": <Order ID>
}
  • When the user accepts, the status will be ‘1’ and message is ‘validated-accepted.’
  • When the user declines, the status will be ‘2’ and message is ‘validated-declined.’