> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# EasyAuthentication

> Re-authenticate returning users with a liveness check — register a liveness record, then match new captures against it with the EasyAuthentication widget.

**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:

| Operation          | What it does                                                        | Needs a `reference_id` |
| ------------------ | ------------------------------------------------------------------- | ---------------------- |
| **Registration**   | Creates the liveness record the user will be matched against later. | No                     |
| **Authentication** | Compares a new liveness capture against that stored record.         | Yes                    |

<Note>
  Authentication needs a valid `reference_id` from a completed registration — or from an [EasyOnboard](/api-reference/hosted-flows-easyonboard/how-hosted-flows-work) session that included a liveness step. Without a record to compare against, there is nothing to authenticate.
</Note>

## How it works

<Steps>
  <Step title="Create an auth flow">
    Create an EasyAuthentication flow in the dashboard. Publishing it produces a `widget_id` that identifies the flow. See [AuthFlows](/dashboard-guide/workflows/easyauthentication/authflows).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Store the reference ID">
    Save the `reference_id` against that user in your own system. You need it for every future authentication.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Widget parameters

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

| Parameter      | Required           | Description                                                                  |
| -------------- | ------------------ | ---------------------------------------------------------------------------- |
| `widget_type`  | Yes                | `register` to create a liveness record, `authenticate` to match against one. |
| `widget_id`    | Yes                | The published EasyAuthentication flow to load.                               |
| `reference_id` | For `authenticate` | The Auth ID returned by the user’s registration.                             |

## Register a user

When the user has no stored liveness record, open the widget with no `reference_id`:

```text Registration URL theme={null}
https://identity.dojah.io/?widget_type=register&widget_id={WIDGET_ID}
```

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](/dashboard-guide/workflows/easyauthentication/customers).

Take the `reference_id` from the [webhook](/api-reference/core-concepts/webhooks-signatures) 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:

```text Authentication URL theme={null}
https://identity.dojah.io/?widget_type=authenticate&widget_id={WIDGET_ID}&reference_id={USER_ID}
```

```text Example theme={null}
https://identity.dojah.io/?widget_type=authenticate&widget_id=698f71930312c0db5b9a7cb2&reference_id=d8065e79-44b5-461b-b6e6-f1c6cdb80c11
```

<Card title="Where USER_ID comes from" icon={<span className="dj-card-emoji">🔑</span>}>
  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`.
</Card>

The new capture is compared against the stored record, a result is returned, and the attempt is logged under [Authentications](/dashboard-guide/workflows/easyauthentication/authentications).

## Statuses

| Status      | Meaning                                         |
| ----------- | ----------------------------------------------- |
| `success`   | The liveness capture matched the stored record. |
| `failed`    | The capture did not match.                      |
| `abandoned` | The user did not finish the flow.               |

<Warning>
  **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](/api-reference/core-concepts/webhooks-signatures).
</Warning>

## 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**.

## Link an EasyOnboard flow

If you already onboard users with EasyOnboard, you can reuse the liveness they captured there instead of registering them a second time:

<Steps>
  <Step title="Include a liveness step">
    The EasyOnboard flow must capture liveness — that capture becomes the base record.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Reuse the reference ID">
    Onboarding produces a `reference_id` you can pass straight to `widget_type=authenticate`.
  </Step>
</Steps>

## 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

<Warning>
  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.
</Warning>

## Related

* [EasyAuthentication in the dashboard](/dashboard-guide/workflows/easyauthentication) — create flows and review every attempt.
* [Liveness check](/api-reference/biometrics-liveness/liveness-check) — run liveness directly against the API instead of the widget.
* [How hosted flows work](/api-reference/hosted-flows-easyonboard/how-hosted-flows-work) — first-time verification with EasyOnboard.
* [Webhooks & signatures](/api-reference/core-concepts/webhooks-signatures) — receive and verify results server-side.