Authentication (REST API)

authenticateExtended

URL

CODE

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

Mandatory parameters:

CODE

&serviceId= <id of the service> //integer
&userId=<login name> //string
&token=<otp generated> //string

Optional parameters:

CODE

&format=json //allows to get the API response in json format instead of XML format
&expectnopin=1  // when using helium with the option withoutpin="1"

Response:

By default, the API response is in XML format

The response contains the following information:

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 helium / windows / mac / android…)
type: type of the device - can be ma (mobile app) / ca (Helium) / mac (an application using maccess)

If the service ID sent in the URL does not reference a valid service ID, the value of “err” will be “NOK:srv unknown”.

If the login name sent in the URL does not match a valid service login name, the value of “err” will be “NOK:account unknown “.

Default response in XML:

XML

<authenticateExtended>
    <err></err>
    <name></name>
    <alias></alias>
    <version></version>
    <platform></platform>
    <type></type>
    <timestamp></timestamp>
</authenticateExtended>

Alternative response format in json:

CODE

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

Possible error codes

'err' values	Reject Reason	Message displayed in admin console	Description
OK	Authenticate OK	OK	Authentication Successful
NOK:no device found	OTP does not match any of the user's devices	KO bad OTP format	Invalid OTP (expired, replay, random, …)
NOK:NOLOGIN	User has not activated a token yet	KO user pending	user not activated
NOK:account unknown	Unknown user	KO unknown user	user doesn't exist
NOK:account disabled	User is blocked	KO user locked	user has been administratively blocked by an operator
NOK:ACCESS	Wrong pin	KO wrong PIN code	user's pin is wrong
NOK_BLOCKED	Device is locked	KO tool locked	user's tool is locked
NOK:no secret	Device needs to be synchronized	KO tool is desynchronized	user's tool is desynchronized
NOK:SN	Syntax Error	KO syntax error	Syntax error. One parameter is missing or incorrect
NOK:TIMEOUT	Request timeout	No message displayed	User didn't respond the request within 1 minute
NOK:Access Forbidden	Client certificate is absent/not valid or IP not whitelisted	-	Client certificate is absent/not valid or IP filtering is activated and the IP address is not in the whitelist (see your service parameters)
NOK	Ooops	KO	Other error. Retry
NOK:HSMERROR	Internal server error	-	Internal server error (TrustBuilder side)
NOK:NO_MATCHING_DEVICE	The OTP may be expired		Could not find a device that have generated the OTP