Complete Factor Verification
/mfa/v1/requests/{requestId}
Request
- application/json
-
requestId: string
Unique identifier of a factor authentication request returned by the server, when the user initiated factor verification
-
Authorization: string
Provide a valid OAuth Access Token that has either the 'Authenticator Client' or 'MFA Client' scope.
object
-
bypassCode(optional):
string
This attribute indicates the pre-generated bypass code that the user wants to use, while authenticating using BYPASSCODE method.
-
otpCode(optional):
string
This attribute provides the one time passcode that the user received over SMS, PHONE_CALL, EMAIL or the TOTP that was generated by the Oracle Mobile Authenticator App enrolled in IDCS. This attribute is only applicable for TOTP, SMS, PHONE_CALL and EMAIL methods.
-
requestState:
string
This contains the context/request related details in encrypted form, which needs to be passed back and forth between server and client. The details are needed by the server to process a request and are opaque to the client.
-
resendOtp(optional):
string
Attribute to indicate if the user wants the OTP to be resent to the mobile number or email id being used to authenticate. Supported values for this attribute are:
- true
- false
-
securityQuestions(optional):
array securityQuestions
List of Security Questions being used for verification
array
-
Array of:
object SecQuesVerification
Use this schema to complete Security Questions factor verification
object
-
answer:
string
Answer to an enrolled security question that the user wants to use for authentication.
-
id:
string
The identifier of an enrolled security question that is being used for authentication by a user.
Response
200 Response
400 Response
401 Response
404 Response
500 Response
Examples
The following example shows how to complete verification of a preferred factor or a backup factor by submitting a PATCH request on the REST resource using cURL. For more information about cURL, see Use cURL.
This method can also be used to request that the time-based one-time passcode (TOTP) be resent when the SMS or EMAIL factors are used.
Factor verification is a 2-step process. You first need to ask Oracle Identity Cloud Service to "initiate" the verification of the factor (for example, send an SMS with a time-based one-time passcode (TOTP), send an email with a TOTP code, or send a PUSH notification to the enrolled Oracle Mobile Authenticator (OMA) app). Use the POST method for this endpoint to initiate the verification.
After initiating, the client needs to "verify" the factor by passing the otpCode,
security answer, accepting a PUSH notification on the OMA app, or using a bypass code.
Note:
There is an Oracle Identity Cloud Service Factor Verification Postman collection available. Download the collection and example environment with variables from the idcs-factor-verification-api folder within GitHub and import them into a REST client.Note:
The command in this example uses the URL structurehttps://tenant-base-url/resource-path,
where
tenant-base-url
represents the Identity Service URL, and the resource path represents the Identity Service API. See
Send Requests for the appropriate URL structure to use.
The following request and response examples are included for this API:
-
Example of a Request Body When Verifying the Preferred SMS/EMAIL/TOTP Factors
-
Example of a Request Body When Verifying the Security Question Factor
-
Example of a Request Body When Requesting That a OTP Be Resent
-
Example of a Response Body When Requesting That a OTP Be Resent
curl
-X PATCH
-H "Content-Type:application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
https://tenant-base-url/mfa/v1/requests/<requestId>
Example of a Request Body When Verifying the Preferred SMS/EMAIL/TOTP Factors
Verify the factor by passing the otpCode
and the requestState
from the initiate verification response (see initiate verification examples on the POST method page for this endpoint), or by accepting the PUSH notification on the OMA app. The following example shows the contents of the request body in JSON format when verifying an SMS/EMAIL/TOTP factor:
{
"otpCode": "629084",
"requestState": "{{requestState}}"
}
Example of a Request Body When Verifying the Security Question Factor
The following example shows the contents of the request body in JSON format when verifying a Security Question factor:
{
"securityQuestions": [
{
"id": "FirstCar",
"answer": "Ford Pinto"
}
],
"requestState": "{{requestState}}"
}
Example of a Request Body Verifying the Bypass Code Factor
The following example shows the contents of the request body in JSON format verifying the Bypass Code factor:
{
"bypassCode": "397541940949",
"requestState": "{{requestState}}"
}
Example of a Response Body When Verifying Factors
The following example shows the contents of the response body in JSON format when verifying factors:
{
"status": "success"
}
The following example shows the contents of the response body in JSON format when the verification fails. The cause
attribute is included that contains the error code and the error message:
{
"status": "failed",
"cause": [
{
"message": "Invalid passcode.",
"code": "AUTH-1105"
}
]
}
{
"status": "failed",
"ecId": "0000MGIHrvfF8DKpISDCif1R9rrp00000G",
"cause": [
{
"code": "AUTH-1111",
"message": "You entered invalid answer(s). Authentication failed."
}
]
}
Example of a Request Body When Requesting That a OTP Be Resent
If the factor is SMS/EMAIL and the user hasn't received the OTP, the client can request that the server to send it again. Every SMS/EMAIL sent increments the user's MFA login attempt count. After the user meets their maximum login attempts, the user account is locked if the user doesn't make a successful login after requesting the OTP. The following example shows the contents of the request body in JSON format when requesting that a OTP be resent. The requestState
is obtained from the initiate verification response (see initiate verification examples on the POST method page for this endpoint):
{
"resendOtp": true,
"requestState": "{{requestState}}"
}
Example of a Response Body When Requesting That a OTP Be Resent
The following example shows the contents of the response body in JSON format when requesting that a TOTP be resent. The response contains the requestID
and the requestState
needed for the next request:
{
"status": "success",
"requestId": "e2746358-a077-41f8-8c16-269b61f3bd87",
"userGUID": "589879c55b7340518141eab82493f0cc",
"factorId": "30db2274140043918edb033d9fe29ff3",
"method": "EMAIL",
"displayName": "user1@example.com",
"requestState": "fMDFvx.....0Rf/CUY"
}