Push request (REST API)

See Authentication API (SOAP API)

This method is used to add a security layer to an existing login / password authentication. For the user, the steps are:

1. Standard login / password authentication

2. Then, multi-factor authentication (MFA) on the mobile, woken up by a Push notification

To achieve this, TrustBuilder provides 2 REST Web Services that enable the push notification.

• PushAuthenticate → requests TrustBuilder platform to send a Push notification to an identified user’s device. This notification wakes up TrustBuilder Authenticator application and prompts for Authorization (using a PIN or not).

• CheckPushResult → allows your server to verify whether MFA for this session was successful or not.

As it is not possible to predict how long the user will take to authenticate, we have implemented an asynchronous procedure:

1. Your server requests TrustBuilder to notify the user’s device, and gets back a session id.

2. Your server verifies periodically with TrustBuilder platform the authentication result of the session.

PushAuthenticate

This requests TrustBuilder platform to send a Push notification to an identified user’s device.

URL

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

Mandatory parameters:

&serviceId= <service id> //integer
&userId=<login of the previsously authenticated user> //string

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 invoqued with 'withoutpin=1'. Default value: 0.

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

• &tooltype=[ma | mac ] → allows to specify the TrustBuilder tool type where to send the push. 'ma' = TrustBuilder Authenticator. 'mac' = mAccess device(s).

• &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.

• &context=<context information> or &context=auto → allows to send a context information in the push notification. It is then possible to display the context information on the mobile device (mAccess and TrustBuilder Authenticator)

  • On TrustBuilder Authenticator the display of the context information is only available on Android and iOS

  • In text mode, the context information must be limited to 128 characters. The context content must respect the following regular expression: ^[\d$%€&@# \.\+\-_\w\p{L}]+$

  • In automatic mode this context consists of a 4 digit string randomly generated. This generated string is available in the response of the API call

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 (can be iphone, android, wp8 in case of Authenticator)

• type: will be “ma” (mobile app) or “mac” (your application developed with mAccess)

• sessionId: the 32-char-long Session Id that will allow you to check Authentication result (to be used in checkPushResult)

• context: the context information provided (field only exists if a context has been passed to the initial call)

Possible error codes:

• NOK:NOPUSH ==> user’s mobile app does not support Push (TrustBuilder nCode)

• 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  ==> Temporary error. In such a case, try to reiterate the API call.

JSON response format:

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

Note that the context field is available only if the call has been made with the context query parameter.

 If your mobile is on a filtered network (WiFi by example), please ensure the following ports are opened to be able to register for push notifications and also to receive them:

• Android (Google):  outbound TCP ports 5228 to 5230.

• iOS (Apple): outbound TCP port 5223 

CheckPushResult

This call is used to get the authentication result of a specific session.

URL:

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

Mandatory parameters:

&serviceId= <service id> //integer
&sessionId=<session id> //string
&userId=<login> //string

Optional parameters:

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

• &withoutpin=1 → if PushAuthenticate is invoqued with 'withoutpin=1', CheckPushResult must also be invoqued with 'withoutpin=1'

Response:

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

• err: the authentication 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 (can be iphone, android, wp8 in case of Authenticator)

• type: will be “ma” (mobile app) or “mac” (your application developed with mAccess)

Possible error codes:

• NOK:WAITING ==> Request is pending, try again later (in 0.5 sec for instance)

• NOK:REFUSED ==> user refused authentication

• NOK:NOMA ==> user does not have any TrustBuilder mobile app available

• NOK:TIMEOUT ==> user did not authenticate in time (1 minute)

• NOK:SN ==> syntax error in input parameters

• NOK:srv unknown ==> serviceId is wrong

• NOK ==> sessionId does not exist or has expired.

JSON response format:

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