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

# Easy Authentication API Guide

> Re-authenticate users with liveness checks using a stored record. Create a liveness registration, then authenticate against it with the Easy Authentication widget. Registration and authentication flows, widget URLs, and dashboard logging.

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

| Status    | Meaning                              |
| :-------- | :----------------------------------- |
| success   | Liveness matched the existing record |
| failed    | Liveness did not match               |
| abandoned | User 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.