Enrollment lookup API contract

Edit online

Almost every external MFA integration must support an ability of ISV Verify find all currently available MFA factor capabilities for a specific user. When run, Verify expects the response to contain a list of JSON objects where each object identifies and represents an MFA capability of the user.

A sample request that is sent by Verify to the enrollments 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 '/enrollments' \
'Content-Type: application/json' \
'Accept: application/json' \

{
    "username": "<<external MFA username>>"
}

Note: The /enrollments HTTP path in this example varies based on the webhook configuration.

Enrollments lookup 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 identifies the user for whom enrollments are requested.
username	Mandatory. The name of a user in the external provider system for which enrollment data is requested.

The following sample is an example of an enrollment lookup response payload.

[
    {
        "attributes": {
            "authExecutionFlow": "init_then_poll",
            "deviceName": "<<Device name if available>>",
        },
        "capability": "<<factor capability name, e.g. push>>",
        "id": "<<factor or device identifier from external provider>>"
    },
    {
        "attributes": {
            "authExecutionFlow": "init_then_validate",
            "deliveryAddress": "<<e.g. phone number or email address>>",
            "deviceName": "<<Device name if available>>",
        },
        "capability": "<<factor capability name, e.g. smsotp>>",
        "id": "<<factor or device identifier from external provider>>"
    },
    {
        "attributes": {
            "authExecutionFlow": "validate",
            "deviceName": "<<Device name if available>>",
        },
        "capability": "<<factor capability name, e.g. totp>>",
        "id": "<<factor or device identifier from external provider>>"
    }
]

Enrollments lookup response details

Elements	Description
Payload type	A JSON array of external MFA enrollments.
HTTP status code	See HTTP Status.
`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. The additional attributes that are returned to the public Verify client that triggered the enrollment lookup. More attributes and values can be present.
`attributes.authExecutionFlow`	Mandatory. Informs Verify of the `MFA pattern` that is supported by the factor capability. Valid values include: `validate` - validate only pattern. `init_then_validate` - Initiate the validate pattern. `init_then_poll` - Initiate then wait for completion pattern. This attribute is used by the Verify external MFA runtime challenge UI/UX and framework to drive runtime execution.
`attributes.deliveryAddress`	Optional. If the execution pattern includes an MFA token delivery or similar experience, then this attribute is displayed by Verify during MFA user selection. This pattern can aid and inform the user choice about the MFA selections that are offered.
`attributes.deviceName`	Optional. If the execution pattern includes an MFA token delivery experience or otherwise includes some kind of separate authentication device or token that is owned by the user, then this attribute is displayed by Verify during MFA user selection. This pattern can aid and inform the user choice about the MFA selections that are offered.