Transaction sealing API (SOAP and REST)

This document describes the API calls used for transaction sealing operations.

To be able to use transaction sealing, parameter "Transaction sealing" must be set to "yes" in the "Service parameters" of your administration console.
If this parameter is not available/displayed in your console, please contact your sales representative at TrustBuilder.

TrustBuilder MFA supports authentication with transactions sealing.

The sealing process is materialized by the following API calls:

SealVerify → Verification after OTP generation
sealDeferredVerify → Verification later

SealVerify (REST)

CODE

https://api.myinwebo.com/FS?action=sealVerify + parameters

Mandatory parameters:

CODE

&serviceId= <id of the service> //integer
&userId=<login> //string
&token=<OTP received from the client app> //string
&data=<sealed data> //string

Optional parameters:

&format=json → allows to get the API response in json format instead of XML format

Response:

By default, response is in XML. It contains:

err: operation result (« OK » or « NOK:<cause> ;»)
name: name of the device that performed the sealing
alias: alias of the device that performed the sealing
version: version of the device that performed the sealing
platform: platform of the device (the one you passed to mAccess)
type: will be “mac” (your application developed with mAccess)
timestamp: timestamp of the API call

If the ID of the service set in the URL is not valid the returned error code is: « NOK:srv unknown ». If the login set is not a valid login of the service the returned error code is: « NOK:account unknown ».

Other error codes:

NOK:NoKey: user does not have a sealing key. This means that he has not activated your app
NOK:BadData: The data sealing in the OTP is different from the one sent in as an input parameter. Potential MITM.
NOK:FORBIDDEN: Sealing option is not authorized for your account. Contact TrustBuilder Sales.
NOK: other errors

Format of XML response:

XML

<sealVerify>
<err>Error Code</err>
<name>appname</name>
<alias>device alias</alias>
<version>app version</version>
<platform>Platform</platform>
<type>mac</type>
<timestamp>timestamp</timestamp>
</sealVerify>

Format of JSON response:

CODE

{"err":"","name":"","alias":"","type":"","version":"","platform":"","timestamp":""}

sealDeferredVerify (REST)

URL:

CODE

https://api.myinwebo.com/FS?action=sealDeferredVerify + parameters

Mandatory parameters:

CODE

&serviceId= <id of the service> //integer
&userId=<login> //string
&token=<OTP received from the client app> //string
&data=<sealed data> //string
&date=<seal date> // timestamp unix (nombre de seconde depuis 01/01/1970)

Optional parameters:

&format=json → allows to get the API response in json format instead of XML format

Response:

By default, response is in XML. It contains:

err: operation result (« OK » or « NOK:<cause> ;»)
name: name of the device that performed the sealing
alias: alias of the device that performed the sealing
version: version of the device that performed the sealing
platform: platform of the device (the one you passed to mAccess)
type: will be “mac” (your application developed with mAccess)
timestamp: timestamp of the API call

If the ID of the service set in the URL is not valid the returned error code is: « NOK:srv unknown ». If the login set is not a valid login of the service the returned error code is: « NOK:account unknown ».

Other error codes:

NOK:NoKey: user does not have a sealing key. This means that he has not activated your app
NOK:BadData: The data sealing in the OTP is different from the one sent in as an input parameter. Potential MITM.
NOK:FORBIDDEN: Sealing option is not authorized for your account. Contact TrustBuilder Sales.
NOK: other errors

Format of XML response:

XML

<sealDeferredVerify>
<err>Error Code</err>
<name>appname</name>
<alias>device alias</alias>
<version>app version</version>
<platform>Platform</platform>
<type>mac</type>
<timestamp>timestamp</timestamp>
</sealDeferredVerify>

Format of JSON response:

CODE

{"err":"","name":"","alias":"","type":"","version":"","platform":"","timestamp":""}

PushSeal (REST)

Requests TrustBuilder platform to send a Push notification to an identified user’s device, for an authentication with seal.

URL

CODE

https://api.myinwebo.com/FS?action=pushSeal + parameters

Mandatory parameters

&serviceId=<service id> → (integer) The service identifier
&userId=<userId> → (string) The login of the authenticated user
&data=<data> → (string) The sealed data

Optional parameters

&withoutpin=1 → when set to 1, push is sent without asking for PIN (overriding global PIN policy). In this case CheckPushResult must also be invoked with 'withoutpin=1'. Default value: 0.
&format=json → allows to get the API response in json format instead of XML format.
&toolalias=<alias of the tool> → allows to specify the tool where to send the push, if several tools have been enrolled by the user. 'toolalias' can be obtained with 'loginQuery' request.

Response

By default, API response is in XML. It contains:

err : the notification result (“OK” or “NOK:<cause>” or “NOK” (=other errors))
name: name of the device that performed the authentication
alias: alias of the device that performed the authentication
version: version of the application that performed the authentication
platform: platform of the device (the one you passed to mAccess)
type: will be “mac” (your application developed with mAccess)
sessionId: the 32-char-long Session identifier that will allow you to check Authentication result (to be used in checkPushResult)
timestamp: timestamp of the API call

Possible error codes

NOK:NOPUSH ==> user’s mobile app does not support Push (TrustBuilder Code)
NOK:NOMA ==> user does not have any TrustBuilder mobile app available
NOK:NOLOGIN ==> user does not exist, or is still pending activation
NOK:SN ==> syntax error in input parameters
NOK:srv unknown ==> serviceId is wrong
NOK:NoKey: user does not have a sealing key. This means that he has not activated your app
NOK:FORBIDDEN: Sealing option is not authorized for your account. Contact TrustBuilder Sales.
NOK ==> Temporary error. In such a case, try to reiterate the API call.

JSON response format

CODE

{"timestamp":"",
"platform":"",
"sessionId":"",
"alias":"",
"name":"",
"err":"",
"type":"",
"version":"",
}

PushSeal (SOAP)

CODE

pushSeal(string userId, string serviceId, string data, string toolalias)

Returns a string

CODE

pushSealResponse