One-factor authentication

Use these raw HTTP examples to complete one-factor authentication with a one-time password (OTP) or token push. Before starting, configure an Authentication API application, assign it a resource rule, and assign the selected authenticator to the user.

OTP

Query the user's authenticators

• Method: POST
• Path: /api/web/v2/authentication/users
• Content type: application/json

{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

The response lists the authenticators allowed by the application's resource rule. The following partial response shows OTP as an available authenticator:

{
  "authenticationTypes": ["OTP", "TOKEN"],
  "otpDeliveryInfo": {
    "otpDefaultDelivery": "SMS",
    "availableOTPDelivery": ["SMS", "EMAIL", "VOICE"]
  }
}

Request the OTP challenge

• Method: POST
• Path: /api/web/v2/authentication/users/authenticate/OTP
• Content type: application/json

{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

IDaaS sends the OTP using the configured delivery method. Store the returned challenge token for the completion request:

{
  "authenticationCompleted": false,
  "token": "<challenge-token>",
  "otpdeliveryType": "SMS"
}

Complete the OTP challenge

• Method: POST
• Path: /api/web/v1/authentication/users/authenticate/OTP/complete
• Authorization: Bearer <challenge-token>
• Content type: application/json

{
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "response": "123456"
}

When the OTP is valid, authenticationCompleted is true, and token contains the IDaaS authentication JWT:

{
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}

An invalid OTP returns an error such as:

{
  "errorCode": "invalid_user_response",
  "errorMessage": ""
}

Token push

Query the user's authenticators

• Method: POST
• Path: /api/web/v2/authentication/users
• Content type: application/json

{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

The following partial response shows token push as an available authenticator:

{
  "authenticationTypes": ["TOKENPUSH", "TOKEN", "OTP"]
}

Request the push challenge

• Method: POST
• Path: /api/web/v2/authentication/users/authenticate/TOKENPUSH
• Content type: application/json

{
  "userId": "jsmith",
  "applicationId": "11111111-1111-1111-1111-111111111111",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001"
    },
    {
      "detail": "Purpose",
      "value": "Transfer"
    }
  ]
}

You can also include pushMessageIdentifier when the tenant has configured a corresponding Soft Token SDK message. For transaction field requirements, see Transaction details and mobile SDK push messages.

Store the returned challenge token:

{
  "authenticationCompleted": false,
  "token": "<challenge-token>"
}

Poll for the push response

• Method: POST
• Path: /api/web/v1/authentication/users/authenticate/TOKENPUSH/complete
• Authorization: Bearer <challenge-token>
• Content type: application/json

{
  "applicationId": "11111111-1111-1111-1111-111111111111"
}

Before the user responds, the endpoint returns:

{
  "status": "NO_RESPONSE",
  "authenticationCompleted": false
}

Continue polling the same completion endpoint with the same challenge token while the status is NO_RESPONSE. Stop when authentication succeeds or the endpoint returns an error. Do not start another challenge for the same pending request.

After the user confirms the request, the endpoint returns the IDaaS authentication JWT:

{
  "status": "CONFIRM",
  "firstName": "John",
  "lastName": "Smith",
  "authenticationCompleted": true,
  "token": "<idaas-jwt>"
}

If the user rejects or cancels the request, the endpoint returns an error such as no_transaction.