Initiate API contract for initiate+validate and initiate+wait pattern

Edit online

The initiate resource is launched by internal Verify components during a runtime MFA challenge when the factor that is used supports the "initiate+validate" or "initiate+wait" integration patterns.

For example, an smsotp or a push. Verify expects the response to contain a status that indicates the success or failure of the MFA initiation and a transaction identifier that is included on the subsequent "validate" or "wait for result" requests. A sample request that is sent by Verify to the initiate resource of the real-time webhook is illustrated in the following example. Depending on the webhook configuration, this same payload can be sent directly to the target MFA provider or transformed to an API client request that is acceptable to the target provider.
POST '/initiate' \
'Content-Type: application/json' \
'Accept: application/json' \

{
  "capability":  "<<factor capability name, e.g. totp>>",
  "id": "<<factor or device identifier from external provider>>",
  "attributes":
    {
      "username": "<<external MFA username>>"
    }
}
Note: The /initiate HTTP path in this example varies based on webhook configuration.

Initiate request details

Element Description
HTTP Request POST
HTTP Header - Content-Type The content type of the request payload is always application/json.
HTTP Header - Accept The content type that is expected of the response payload is always application/json.
Payload A JSON object that represents the token or pass value to be validated. The payload also identifies the user and their associated MFA enrollment or registration.
id

Mandatory. The unique identifier of the user's enrolled or registered MFA factor capability.
capability

Mandatory. The value is valid character string. It must match one the capabilities that are configured for the MFA provider that is associated with the webhook.
attributes

Mandatory. Request-specific additional attributes.
attributes.username Mandatory. The name of a user in the external provider system for which MFA initiation is requested.
The following code sample is an example of the initiate response payload.
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

Initiate response details

Elements Description
Payload type A JSON object that represents MFA initiation attempt status.
HTTP status code See HTTP Status.
status Mandatory. The validation completion status. Valid values include SUCCESS, PENDING, TIMEOUT, CANCELED, and FAILED
Note: Returning a status of SUCCESS to the Initiate call results in an error to the end user. SUCCESS is not a valid Status for the Initiate call

If the MFA provider supports OTP retry the 'status' must come back as 'PENDING'.
transactionId

Mandatory. Transaction or other MFA provider authentication challenge state handle. Used by the provider to correlate with any subsequent "validate" or "result poll" calls.
attributes

Optional. The additional attributes that are returned to the public Verify client that triggered the MFA challenge. Any attributes and values can be present.