Authentication with an OTP via the OpenID API

To validate the transaction, the received OTP should be used to proceed as an Resource Owner Authentication (password grant type) via the OpenID token endpoint.

As a parameter in addition to the normal "password" grant type, the challengeId is required to find the corresponding challenge paired with the OTP. Eventually, the correlationid should be passed if the original challenge is generated with a correlationid.

Specific parameters which can be passed in the context parameter with the following format:

Copy

context=PARAM1:VALUE1:isForAUDIT PARAM2:VALUE2:isForAudit

(where isForAudit is either true or false)

correlationId – only mandatory if it is passed when using DELIVER-CHALLENGE. If present, it will be checked against the value saved in the challenge.
txID – mandatory, the challenge id generated during DELIVER-CHALLENGE.

Note: noToken is a common parameter for the OpenID token endpoint (HID customized). It is useful if the application only needs to validate the password without generating a session each time.

Authentication with OTP via OpenID (No Session)

Copy

Sample request

POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1Content-Type: application/x-www-form-urlencoded
 
password=49991081&grant_type=password&context=correlationId%3A1111%3Afalse+txID%3A21088%3Afalse&channel=CH_SSP&authType=AT_TXOOB&client_id=spl-api&username=SMS_User&client_secret=password01&noToken=1

Copy

Sample response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
 
{"access_token":"IA==","context":{"LEVEL_OF_ASSURANCE":"2"},"token_type":"Bearer"}

Authentication with OTP via OpenID (Create Session)

Copy

Sample request

POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
 
password=49991081&grant_type=password&context=correlationId%3A1111%3Afalse+txID%3A21088%3Afalse&channel=CH_SSP&authType=AT_TXOOB&client_id=spl-api&username=SMS_User&client_secret=password01&noToken=0

Copy

Sample response

HTTP/1.1 200 OK
Cache-Control: no-store
Pragma: no-cache
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
 
{
"access_token": "fFa87gAAAW0Wzg/dj50JeGX5Q9HgEPh0wF7AYDsl",
"context": {"LEVEL_OF_ASSURANCE": "2"},
"token_type": "Bearer",
"expires_in": 86400
}

Sample Error Responses

Copy

Wrong transaction id (txID)/challenge id

HTTP/1.1 400 Bad Request
 
{
"hid_failure":{
"reason":49,
"authType":"AT_TXOOB"
},
"error_description":"Invalid grant: Resource owner username or password is invalid (Cannot find delivery challenge):Resource owner username or password is invalid","error":"invalid_grant"
}

Copy

Wrong correlation id

HTTP/1.1 400 Bad Request
 
{
"hid_failure": {
"reason": 17,
"authType": "AT_TXOOB"
},
"error_description": "Invalid grant: Resource owner username or password is invalid (Given challenge does not match the last issued challenge):Resource owner username or password is invalid",
"error": "invalid_grant"
}

Copy

Missing transaction id

 HTTP/1.1 400 Bad Request
 
{
"hid_failure": {
"reason": 30,
"authType": "AT_TXOOB"
},
"error_description": "Invalid grant: Resource owner username or password is invalid (Reason indicating it is required to provide challenge for asynchronous authentication):Resource owner username or password is invalid",
"error": "invalid_grant"
}

Copy

Expired OTP

HTTP/1.1 400 Bad Request
 
{
"hid_failure": {
"reason": 22,
"authType": "AT_TXOOB"
},
"error_description": "Invalid grant: Resource owner username or password is invalid (Challenge expired):Resource owner username or password is invalid",
"error": "invalid_grant"
}

Copy

Credential not valid (for example, revoked or expired)

HTTP/1.1 400 Bad Request
 
{
"hid_failure": {
"reason": 23,
"authType": "AT_TXOOB"
},
"error_description": "Invalid grant: Resource owner username or password is invalid (No valid credentials were found for that user):Resource owner username or password is invalid",
"error": "invalid_grant"
}

Copy

Wrong OTP

HTTP/1.1 400 Bad Request
 
{
"hid_failure":{
"reason":13,
"authType":"AT_TXOOB"
},
"error_description":"Invalid grant: Resource owner username or password is invalid (Password does not match):Resource owner username or password is invalid","error":"invalid_grant"
}