Completing an Identity Challenge
Identity Challenges are used to verify the user’s identity when performing secure actions, such as creating external transfers. Read the Identity Challenges article for more information.
If an identity challenge is required for an operation, the API responds with a 401 — Unauthorized code with a Challenge Required problem response. The document goes over in detail the steps for performing an identity challenge, including:
- Present the user with appropriate challenge factors
- Allow the user to choose a challenge factor
- Start the selected factor
- Confirm the user’s answers
- If the user’s answers failed, retry the identity challenge as appropriate
- Once the user is validated, retry the original API request with an additional Challenge header
Getting Available Challenge Factors
The attributes.factors in the problem response lists the challenge factors that the client may choose to verify their identity, as described in the requiredIdentityChallenge schema.
The challenge factors available are:
sms: One-time passcode (OTP) is sent to the user’s mobile phone number over SMS.email: One-time passcode is sent to one or more of the user’s email addresses.voice: One-time passcode is communicated via automated voice phone call.securityQuestions: The user must answer security questions that are registered with their security profile.
Each factor type contains extra information that is used to perform the identity challenge. Factors that use OTP have labels showing which phone numbers or email addresses can be used for validation. Security questions do not have labels. Instead, security question factors contain a list of questions that have a prompt field with the content of the security question.
An example of a list of factors a user can choose from is shown below:
{
"operationId": "createTransfer",
"challengeId": "0504076c566a3cf7009c",
"factors": [
{
"type": "sms",
"labels": [
"9876"
],
"id": "85c0ee5753fcd0b0953f"
},
{
"type": "voice",
"labels": [
"9876"
],
"id": "d089e10a80a8627df37b"
},
{
"type": "email",
"labels": [
"an****nk@example.com",
"an****98@example.com"
],
"id": "e917d671cb2f030b56f1"
},
{
"type": "securityQuestions",
"securityQuestions": {
"questions": [
{
"id": "q1",
"prompt": "What is your mother's maiden name?"
},
{
"id": "q4",
"prompt": "What is your high school's name?"
}
]
},
"id": "df33c6f88a37d6b3f0a6"
}
]
}
Note: The challenge request contains every factor available for that operation. The user may have more or less factors available for different operations, depending on the FI’s security settings.
The user is allowed to select which factor they want to use to answer the identity challenge. The application should present the list of challenge factors to the user.
Ensure that the application lists every available label as well as challenge type; the user may have multiple contact methods for similar verification processes. For example, a user with a work mobile phone and a personal mobile phone may be able to choose which phone number to send the OTP SMS.
Note: OPTs can send to multiple email addresses for one request. A user with two email addresses on file would get the OPT to each address.
Once the user has selected their preferred challenge factor, the application needs to perform the identity challenge.
Starting an Identity Challenge
Starting an identity challenge sets the selected challenge factor as active. The user must validate their identity using the active challenge factor.
Note: If the user needs to select a new challenge factor, the application needs to restart the identity challenge process. This is discussed in the Processing Identity Verification section.
To start an identity challenge, you will need to POST a startIdentityChallenge operation request.
POST https://api.apiture.com/banking/challenges/startedChallenges
The request body must contain the operationId, challengeId, factorId, and the factor the user selected:
{
"operationId": "createTransfer",
"challengeId": "b8cae0901002bba4e2a7",
"factor": "sms",
"factorId": "85c0ee5753fcd0b0953f"
}
The operationId and challengeId are available in the Challenge Response body.
Once the challenge has been started, the user is provided with the one-time passcode via method they selected or are shown the security questions needed for validation.
Validating Security Questions
The available security questions were sent in the Challenge Response body and should already be available for display in the application’s user interface. All of the security questions provided must be answered correctly to pass the identity challenge.
The minimumResponseLength and maximumResponseLength for the characters in each answer is available in the startIdentityRequest response.
Once the user has answered all of the security question(s), a verifyIdentityChallenge request asks for validation of the user’s answers to the security question.
POST https://api.apiture.com/banking/challenges/verifiedChallenges
with the factor, operationId, challengeId, and responses included in the request body, as seen in the example below:
{
"factor": "securityQuestions",
"operationId": "createTransfer",
"factorId": "be6177eff07649128e40",
"challengeId": "dec42c64402319a59ec7",
"responses": [
{
"promptId": "q1",
"response": "Smith"
},
{
"promptId": "q4",
"response": "Kinston High School"
},
{
"promptId": "q9",
"response": "Walter"
}
]
}
}
Note: The security questions are already available to display to the user without using a startIdentityRequest operation beforehand. After the application has received the security question answers from the user, the application may perform the startIdentityRequest operation and, once a response has been received, then immediately perform a verifyIdentityChallenge containing the user’s answers. This workflow is not possible for other challenge factors.
Validating One-Time Passcodes
The system sends the one-time passcode to the user via the method they requested. Once the passcode is received, the user should enter the passcode into the application’s interface.
The minimumResponseLength and maximumResponseLength for the digits the OTP is available in the startIdentityRequest response. The hyphen is not included in the character count.
Once the user has provided a OTP, a verifyIdentityChallenge request asks for validation of the user’s answers to the security question.
POST https://api.apiture.com/banking/challenges/verifiedChallenges
with the factor, operationId, challengeId, and responses included in the request body, as seen in the example below:
{
"factor": "sms",
"operationId": "createTransfer",
"factorId": "9f6305571a38f8d584ac",
"challengeId": "dec42c64402319a59ec7",
"responses": [
{
"response": "987303"
}
]
}
If the user does not receive the OTP, the startIdentityChallenge operation can be called again for either the same or a different challenge factor. The previously started challenge factor is then set as inactive and the new factor as active.
Verifying Identity Challenges
The verifyIdentityChallenge response includes one of the following result values:
failed: the verification answer(s) did not match the expected responselocked: the user has failed too many verification attempts. The user cannot continue answering the identity challenge immediately.verified: the verification answer(s) matched the expected responseexpired: the corresponding identity challenge has expired
If the user has failed verification, they may be able to submit a new response, restart the same challenge factor, or try the operation again to get a new challenge. The verifyIdentityChallenge response includes the allows object to see what steps the user is able to take next. The user may be able to do any of the following if the property in the allows object is set to true:
retry: the user may retry a challenge by selecting any of the original challenge factors and starting and verifying that challenge factor.restart: the user may restart this challenge factor. The application must send astartIdentityChallengerequest again with the same factor.reverify: the user may enter a new response to this challenge. The application needs to call theverifyIdentityChallengewith a different response.
If the user is locked from continuing the identity challenge, they are unable to proceed at this time. Most challenges can be restarted after a 24-hour waiting period or be manually unlocked by the FI, but the depends on FI’s security settings and protocols.
If the result is verified, the client should retry the original API operation again.
Retrying the Original Operation after Verification
The application should attempt to retry the original operation that required an identity challenge. The data in the original request should match exactly what was sent during the first attempt, but with one additional header.
In addition to the bearer token used for authentication, the header should include a Challenge token. This Challenge header should pass the value of the challengeToken provided by a verified verifyIdentityChallenge response. An example Challenge header is shown below:
Authentication: Bearer eyJraWQi...VVb1pH9bcBbg
Challenge: 91a2a7724d6e82f5cd73The Challenge header is used to confirm that the user successfully completed an identity challenge and that the original operation is allowed to continue as normal.trying