Validate API contract for initiate+validate or validate only patterns

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

For example, an smsotp or a totp. Verify expects the response to contain a status that indicates the success or failure of the validation request attempt. A sample request that is sent by Verify to the initiate resource of the realtime 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 '/validate' \
'Content-Type: application/json' \
'Accept: application/json' \

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

Validate 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. Identifies the MFA factor capability type. 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.

transactionId

Optional. Transaction or other MFA provider authentication challenge state handle. This value is present if the validation is performed as part of the "initiate+validate" pattern flow. Its value is the same as that included in the prior "initiate" response.

attributes

Mandatory. Validate request-specific additional attributes.

attributes.username

Mandatory. The name of a user in the external provider system for which validation is requested.

attributes.passvalue

Mandatory. The token or value to be validated.

The following code is a sample validate response payload.
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS"
}

Validate response details

Elements Description
Payload type A JSON object that represents validation attempt status.
HTTP status code See HTTP Status.
status Mandatory. The validation completion status. Valid values include SUCCESS, PENDING, TIMEOUT, CANCELED, and FAILED
attributes Optional. Additional attributes that are returned to the public Verify client that triggered the MFA challenge. Any additional attributes and values can be present.