1. REST API for Oracle Identity Cloud Service
  2. Tasks
  3. On-Demand MFA
  4. Factor Verification

Initiate Factor Verification

post

/mfa/v1/requests

Request

Supported Media Types
Header Parameters
  • Provide a valid OAuth Access Token that has the 'Authenticator Client' or 'MFA Client' scope.
Body ()
Initiate Factor Verification Schema
Root Schema : InitiateFactorVerification
Type: object
Use this schema to initiate factor verification on a default factor or a backup factor
Show Source
  • This attribute is considered only for the PUSH method. The name of the application protected by MFA, that the user is trying to access. This application name will appear in the Mobile App Notification on the Oracle Mobile Authenticator App, when a user authenticates using PUSH method.
  • The unique identifier of an enrolled factor that the user wants to use to authenticate. This attribute should only be provided if the user is using a non default factor for authentication. In case of SECURITY_QUESTIONS method, the factorId should be set to 'SecurityQuestions'
  • The ip address of the machine from where the user's request originated. This ip address will appear in the Mobile App Notification on the Oracle Mobile Authenticator App, when a user authenticates using PUSH method.
  • It indicates the method that the user wants to use to authenticate for MFA. Supported values for this attribute are:
    • SMS
    • PHONE_CALL
    • TOTP
    • PUSH
    • EMAIL
    • SECURITY_QUESTIONS
    • BYPASSCODE

    This attribute should only be provided if the user is using a non default factor for authentication.
  • This attribute is considered only for the PUSH method. The name of the user agent or browser that the user is using to access a MFA proected application. This user agent name will appear in the Mobile App Notification on the Oracle Mobile Authenticator App, when a user authenticates using PUSH method.
  • The unique identifier of the user who wants to initiate a factor verification. This can either be the username or the userGuid.
  • This attribute indicates what type of credential the user is providing. Users are allowed to provide their username or userGuid. Supported values for this attribute are:
    • USER_NAME
    • USER_GUID
    The value provided for this attribute should correspond to the value supplied in the userId attribute.
Back to Top

Response

200 Response

Indicates that the authentication request was accepted and initiated successfully.

400 Response

Indicates a bad request, since the request payload is invalid.

401 Response

Indicates unauthorized access if the token provided is invalid or if the user is either locked, inactive, or not enrolled in MFA.

500 Response

Internal Server error
Back to Top

Examples

The following examples show how to initiate verification of a default factor or a backup factor by providing the userId when submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL.

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).

After initiating, the client needs to verify the factor by passing the otpCode, security answer, or accepting a PUSH notification on the OMA app. Use the PATCH method for this endpoint to verify factors.

If you need to use the API without getting the userGUID, you can use it by providing any of the user unique ids such as username/email. See the Request Examples of Getting Enrolled Factors for a User section below for how to request enrolled factors by the userGUID or filtering by user name.

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 structure https://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 Initiating Verification of the Preferred Factor

The following examples show the contents of the request body in JSON format when initiating verification of a default factor. The userIdType in the request indicates what type of credential the user is passing as the value for the userID. The following userIdType values are accepted: USER_GUID and USER_NAME.

{
   "userId":"{{userGUID}}",
   "userIdType": "USER_GUID"
}

Example of a Response Body When Initiating Verification of the Preferred Factor (EMAIL)

The Email, SMS, and TOTP responses are very similar. The following example shows the contents of the response body in JSON format when initiating verification for EMAIL as the default factor. The response contains the requestId and the requestState needed for the next request (which is to verify the factor using the PATCH method): 

{
    "status": "success",
    "requestId": "ede6f855-a678-415b-930d-9b4d730df9cb",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "method": "EMAIL",
    "displayName": "user1@example.com",
    "requestState": "xcWIJPRWYu.....NeKd0oIOw"
}

The Security Questions response is a bit different, as it includes the security question id, the security question hintText, and the security question localizedText attributes: 

{
    "status": "success",
    "requestId": "031cf9ac-cc03-49a2-848e-751aad8b5db0",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "SecurityQuestions",
    "method": "SECURITY_QUESTIONS",
    "requestState": "mNFUnEl9MYL0....prrIIrvX7cDCaF0mxQ",
    "securityQuestions": [
        {
            "id": "FirstCar",
            "hintText": "Found on road dead",
            "localizedText": "What's the model of your first car?"
        }
    ]
}

Example of a Request Body When Initiating Verification of a Backup Factor

If the user doesn't want to use the default factor, the user has the option to provide the factorId and method to indicate that they want to use one of their backup factors. The following example shows the contents of the request body in JSON format when initiating verification of a backup factor. PUSH is the factor used in this example. The request body is very similar for all backup factors: 

{
    "userId":"{{userGUID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"PUSH"
}

Example of a Response Body When Initiating Verification of a Backup Factor

The following example shows the contents of the response body in JSON format when initiating verification of a backup factor. The response contains the requestId and the requestState needed for the next request (which is to verify the factor using the PATCH method). The response body is very similar for all backup factors, except Security Questions. That example is also provided: 

{
    "status": "success",
    "requestId": "61a35b3b-3ecd-4183-8c3c-e5f6941cbd88",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "88178d80636a428393a5674ba46dc867",
    "method": "SMS",
    "displayName": "+15XXXXXX555",
    "requestState": "M7w1Lqb1x........AiopM"
}

The Security Questions response is a bit different, as it includes the security question id and the security question localizedText attributes: 

{
    "status": "success",
    "requestId": "8da79411-5388-41ee-990e-935e74cb40f3",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "SecurityQuestions",
    "method": "SECURITY_QUESTIONS",
    "requestState": "hBJIvkyfsXBv....movYarft8HlYANV3c+0",
    "securityQuestions": [
        {
            "id": "MaidenName",
            "localizedText": "What's your mother's maiden name?"
        }
    ]
}
Back to Top