State models

Status Response Model Action Description

USER_ID_REQUIRED

This state has no model.

  • checkuserId
  • cancel

The user must select the one-time device from the list to proceed with the authentication flow.

AUTHENTICATOR_SELECTION_REQUIRED

  • authenticators: The list of authenticators available to the user.
  • selectAuthenticator
  • cancel

The user must select an authenticator for authentication.

INPUT_REQUIRED

  • authenticator (string): The authenticator that the user selected.
  • gridChallenge (GridChallenge): The information that's needed for grid authentication.
  • kbaChallenge (KbaChallenge): The information that's needed for KBA authentication.
  • tokenPushMutualChallenge (string): The optional token push mutual challenge that's received.
  • checkInput
  • showAlternativeAuthentication
  • resendAuthenticationRequest
  • cancel

The user must complete authentication via an input.

ENTRUST_FAILED

  • code (string): The error code.
  • message (string): The developer-facing error message.
  • userMessage (string): The user-facing error message.
  • cancel

Entrust authentication failed.

Action models

Action Request Model Errors Description

checkuserId

  • userId (string): The user ID that's used for authentication.

This action has no errors.

Submits the user ID for authentication.

cancel

This action has no model.

This action has no errors.

Cancels the current operation.

selectAuthenticator

  • authenticator (string): The authenticator that the user selected.
  • Error: VALIDATION_ERROR

Selects an authenticator as an authentication method.

checkInput

  • input (string): The response that's required for authentication.
  • answers(array[KbaAnswer]): The KBA response that's required for authentication.
  • Error: VALIDATION_ERROR

Validates the input from the user.

showAlternativeAuthentication

This action has no model.

This action has no errors.

Shows the list of alternative authentication options.

resendAuthenticationRequest

This action has no model.

  • Error: VALIDATION_ERROR

Resends the current authentication request.

Objects

GridChallenge
Parameter Name Type Description

cells

String array

The cells used for the input.

numCharsPerCell

Integer

The number of characters per cell.

serialNumbers

String array

The list of serial numbers of the grid cards that can be used.

KbaChallenge
Parameter name Type Description

id

String

The ID used for the challenge.

userQuestions

Array of UserQuestion

The questions used for the input.

UserQuestion
Parameter name Type Description

id

String

The ID for the user question.

question

String

The question value for the user question.

answer

String

The answer value for the user question.

KbaAnswer
Parameter name Type Description

id

String

The ID of the question.

answer

String

The answer value for the question.

Error Codes

An error code is returned if the call flow state has not reached a dead end, and the user can still authenticate with a device.

Top level error codes
Error code Message HTTP status

VALIDATION_ERROR

One or more validation errors occurred.

400

Detail level error codes
Error code Message userMessageKey Parent code

INVALID_AUTHENTICATOR

Selected authenticator is not a valid form of authentication.

invalid.authenticator

VALIDATION_ERROR

INVALID_INPUT

The input entered is incorrect.

invalid.input

VALIDATION_ERROR

INVALID_INPUT_FORMAT

The format of input is incorrect.

invalid.input.format

VALIDATION_ERROR

GENERAL_ERROR

Authentication error.

general.error

VALIDATION_ERROR

ACCOUNT_LOCKED_OUT

The user account is locked.

account.locked.out

VALIDATION_ERROR

PUSH_CANCELLED

User canceled push notification transaction.

push.cancel

VALIDATION_ERROR

PUSH_SUSPICIOUS

User marked the push notification transaction as suspicious.

push.suspicious

VALIDATION_ERROR