Authentication Transaction

authID Verified Transactions enables organizations to strengthen security and protect their users using Biometric Authentication transaction context to improve security and compliance further.

Before requesting Authentication Transaction to be generated, authID Account has to have biometric or passwordless credential enrolled.

Integration can invoke user verification at any time user identity confirmation is required, e.g. at login or any privileged action effectively implementing zero trust policy.


API Sequence

The overall sequence of API calls and other action the integration has to follow is straightforward and almost identical to Proof (IDV) transaction and other enrollment-type transactions.

Verified with Embedded UX




Create Authentication Transaction

To begin the process of authenticating the user's identity using authID account credentials and/or attributes, the new transaction must be requested via API using the New Transactions Endpoint.

The example of POST body:

{
    "AccountNumber": "AccountV2",
    "Timeout": 3600,
    "ConfirmationPolicy": {
        "TransportType": 0,
        "CredentialType": 1,
        "BioPolicy": {
            "CheckLiveness": true
        }
    },
    "Name": "Verify_Identity"
}

Transaction Template Name

The Name parameter is required and must refer to existing configured transaction template. Every Customer Sanbox/Teanant comes with at least one named template "Verify_Identity"

New templates and template customization can be requested from authID support and include multiple elements such color schema, email branding, SMS content, logos, and more.

Confirmation Policy

Confirmation Policy object is required, developers must construct policies by including the Transport Type, Credential Type and additional items depending on Credential Type specified for the policy.

"ConfirmationPolicy": {  
  "TransportType": 2,  
  "CredentialType": 4  
}

πŸ“˜

Effect of Selected Policy on User Experience and Security

Please visit Verified Confirmation Policies page for more details.

The Credential Types

CredentialTypeDescription
0Basic (web link only, no credential)
1Biometrics
2OTP
4FIDO

The Transport Types

TransportTypeDescription
0Embedded \ Inline
1SMS
2Email

Using TransportType 0 returns a TransactionId and an OneTimeSecret. Save these values from the response and use them to deliver the UI to the user. Example response body:

{  
   "TransactionId": "c4f2014f-9c43-665a-af52-a78d13da0503",
   "OneTimeSecret": "Uw6ZwefA5FEBV9furMYlvFBs"  
}

Display the User Interface

Use the values from previous step to display the embedded capture experience to the user.

The other options for TransportType parameter usage are described in the Out-of-band Transactions section.


Wait for the User to Complete Authentication

When the user completes Authentication, the status changes from 0 - Pending to another status. Refer to the Transaction Statuses section for more details.

πŸ‘

Authentication Success Status

Only 1 - Accepted signifies "authentication success", any other status must be treated as "authentication failed"

The application has several ways to detect when the status changes.

  • Periodic poll of backend for Enrollment operation status change using Transaction Status Endpoint
  • Embedded Integration can listen to Web Component Events for web integration or to JavaScript bridge events for WebView integration. The UI emits the signal that the user has reached the "final page" of the experience.

Please refer to the Web Component Events section for more details.

The best strategy from both a UX transition reaction time and system load perspective is to:

  • Listen to events from the Web Component / WebView.
  • When the user reaches the final page, pass the signal from your application frontend to your application's backend.
  • Confirm the status change via the backend Transaction Status Endpoint.
  • As a backup, poll status changes periodically using Transaction Status Endpoint, for example, once every 5 seconds.

Both Out-of-band and Embedded integrations can use Webhook to receive notifications when the status changes. Note that webhooks are not queued and do not have guaranteed delivery, so the periodic polling backup strategy still applies.