Skip to main content
EasyAuthentication confirms a returning user by comparing a fresh liveness capture against a liveness record you already hold for them. Instead of running full identity verification again, the user takes a short liveness check. There are two operations, and the same widget performs both:
Authentication needs a valid reference_id from a completed registration — or from an EasyOnboard session that included a liveness step. Without a record to compare against, there is nothing to authenticate.

​
How it works

1

Create an auth flow

Create an EasyAuthentication flow in the dashboard. Publishing it produces a widget_id that identifies the flow. See AuthFlows.
2

Register the user

Open the widget without a reference_id. The user completes a liveness capture, Dojah stores it as their base record, and a reference_id is returned.
3

Store the reference ID

Save the reference_id against that user in your own system. You need it for every future authentication.
4

Authenticate later

Open the widget with the user’s reference_id. The new capture is matched against the stored record and a result is returned.

​
Widget parameters

The widget is opened as a URL on https://identity.dojah.io/:

​
Register a user

When the user has no stored liveness record, open the widget with no reference_id:
Registration URL
The user completes the liveness capture, a new liveness record is created, and a reference_id (also shown as the Auth ID) is generated. The session is logged under Customers. Take the reference_id from the webhook rather than the dashboard, so registration is captured automatically.

​
Authenticate a returning user

Open the widget with the reference_id you stored for that user:
Authentication URL
Example

Where USER_ID comes from

The USER_ID in this authentication URL is generated by Dojah automatically — you do not create it yourself. It is returned in the dashboard or via webhook (EasyOnboard notification) after registration or an EasyOnboard session that included a liveness step. Pass that value as reference_id.
The new capture is compared against the stored record, a result is returned, and the attempt is logged under Authentications.

​
Statuses

Don’t decide on the client. Treat the widget callback as a signal that the flow finished, not proof that the user passed. Confirm the status server-side from the webhook before you release a sensitive action — see Webhooks & signatures.

​
Rules to know

  • No reference_id means registration — a new liveness record is created.
  • A valid reference_id means authentication — the capture is matched against the existing record.
  • An invalid reference_id causes authentication to fail.
  • Authentication never overwrites the registration record, so the base capture stays stable over time.
  • Registration and authentication sessions are logged separately, under Customers and Authentications.
If you already onboard users with EasyOnboard, you can reuse the liveness they captured there instead of registering them a second time:
1

Include a liveness step

The EasyOnboard flow must capture liveness — that capture becomes the base record.
2

Link the flow

Link the EasyOnboard flow in your EasyAuthentication flow before the user completes onboarding verification. Linking it afterwards won’t backfill existing sessions.
3

Reuse the reference ID

Onboarding produces a reference_id you can pass straight to widget_type=authenticate.

​
Integration methods

The widget can be opened as a redirect URL, in a JavaScript WebView, or in an embedded iframe. Whichever you use, include the reference_id when authenticating.

​
Handling the reference ID

A reference_id is the key to a user’s stored biometric record. Store it server-side alongside your user record, never in localStorage, cookies, or a URL you log. Anyone who can supply a valid reference_id can attempt authentication against that record.