Skip to main content
Easy Authentication lets you re-authenticate users by comparing a new liveness capture to a previously stored liveness record. You can skip full identity verification and use a short liveness check instead. Two operations are supported:
  • Registration – Creates a liveness record for a user.
  • Authentication – Compares a new liveness capture to an existing record.
Authentication needs a valid Reference ID from a completed registration or onboarding session.

​
Authentication Flow

​
Step 1: Create an Authentication Flow

Create an Easy Authentication Flow in the dashboard before starting any session. The flow gives you a widget_id, which you need to launch the widget.

​
Step 2: Registration (When No Liveness Record Exists)

If the user has no stored liveness record, open the authentication widget without a reference_id. Widget URL format: 
https://identity.dojah.io/?widget_type=register&widget_id={WIDGET_ID}
What happens:
  • The user completes liveness capture.
  • A new liveness record is created.
  • A Reference ID (Auth ID) is generated.
  • The session appears under the Customers tab.
Store the reference_id from the webhook or from the dashboard. You need it for later authentication.

​
Step 3: Authentication (Re-Authentication)

To authenticate a user who already has a liveness record, open the widget with that user’s reference_id. Widget URL format: 
https://identity.dojah.io/?widget_type=authenticate&widget_id={WIDGET_ID}&reference_id={REFERENCE_ID}
Example: 
https://identity.dojah.io/?widget_type=authenticate&widget_id=698f71930312c0db5b9a7cb2&reference_id=d8065e79-44b5-461b-b6e6-f1c6cdb80c11
What happens:
  • The user completes liveness capture.
  • The new capture is compared to the stored liveness record.
  • An authentication result is returned.
  • The session appears under the Authentications tab.

​
Status Values

StatusMeaning
successLiveness matched the existing record
failedLiveness did not match
abandonedUser did not finish the flow

​
Dashboard Logging

​
Customers Tab

Shows:
  • Registration sessions
  • Liveness base records
  • Reference ID
  • Auth ID
  • Session ID
  • Timestamp

​
Authentications Tab

Shows:
  • All re-authentication attempts
  • Reference ID
  • Auth ID
  • Session ID
  • Status (success, failed, or abandoned)
  • Timestamp

​
Linking EasyOnboard (Optional)

If you use EasyOnboard:
  • The EasyOnboard flow must include a liveness step.
  • Link the EasyOnboard flow in Easy Authentication.
  • Liveness from onboarding is then used as the registration record.
  • A Reference ID is created and can be reused for authentication.
Link the flow before the user completes onboarding verification.

​
Integration Methods

You can open the widget by:
  • Redirect URL
  • JavaScript WebView
  • Embedded iframe
For authentication, always include the reference_id (Auth ID) in the request.

​
Important Rules

  • No reference_id means registration (new liveness record).
  • Valid reference_id means authentication (match against existing record).
  • Invalid reference_id causes authentication to fail.
  • Authentication does not replace or overwrite the registration record.
  • Registration and authentication sessions are logged in separate tabs.

​
Best Practices

  • Store reference_id securely in your system.
  • Use authentication only for high-risk or sensitive actions.
  • Use Authentication Analysis to track success and failure patterns.