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

# Auth Engine

> Embed identity verification into your authentication flows.

The Auth Engine integration adds step-up identity verification to your login, registration, and account recovery flows. Verify users at the moment of authentication with configurable verification profiles and automatic redirects.

## Prerequisites

* An application with an existing authentication system
* Verilock Business or Enterprise plan

## How It Works

Auth Engine sits between your authentication system and the protected resource. When a user triggers a verification requirement, they are redirected to the Verilock hosted flow, verified, and returned to your application with a signed result.

```
User Login ──> Your Auth System ──> Verilock Auth Engine ──> Hosted Verification
                                                                     │
                                                                     v
User Granted Access <── Your Callback URL <── Signed Result ◄────────┘
```

## Setup

<Steps>
  <Step title="Register Your Application">
    Go to **Dashboard > Settings > Integrations > Auth Engine** and register your application:

    * **Application Name**: Your app's display name
    * **Callback URL**: Where to redirect after verification (e.g., `https://yourapp.com/auth/verilock/callback`)
    * **Allowed Origins**: Domains permitted to initiate verification
  </Step>

  <Step title="Choose a Verification Profile">
    Select the verification level required for your flow:

    | Profile      | Steps                                                     | Use Case                     |
    | ------------ | --------------------------------------------------------- | ---------------------------- |
    | **Basic**    | Document capture only                                     | Low-risk account creation    |
    | **Standard** | Document + selfie + face match                            | Standard onboarding          |
    | **Enhanced** | Document + selfie + face match + liveness + address proof | Regulated financial services |
  </Step>

  <Step title="Configure Callback Handling">
    After verification, Verilock redirects the user to your callback URL with a signed token:

    ```
    https://yourapp.com/auth/verilock/callback?token=eyJhbGciOiJSUzI1NiIs...&session_id=ses_a1b2c3d4e5f6
    ```

    Verify the token server-side before granting access.
  </Step>

  <Step title="Implement the SDK">
    Use the Verilock SDK to initiate verification from your frontend.
  </Step>
</Steps>

## SDK Integration

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    import { VerilockAuth } from '@verilock/auth-engine';

    const auth = new VerilockAuth({
      clientId: 'your_client_id',
      callbackUrl: 'https://yourapp.com/auth/verilock/callback',
      profile: 'standard'
    });

    // Trigger verification
    document.getElementById('verify-btn').addEventListener('click', () => {
      auth.startVerification({
        applicant: {
          email: 'user@example.com',
          external_id: 'usr_12345'
        },
        autoRedirect: true
      });
    });
    ```
  </Tab>

  <Tab title="React">
    ```javascript theme={null}
    import { useVerilockAuth } from '@verilock/auth-engine-react';

    function VerifyButton() {
      const { startVerification, isLoading } = useVerilockAuth({
        clientId: 'your_client_id',
        callbackUrl: 'https://yourapp.com/auth/verilock/callback',
        profile: 'standard'
      });

      return (
        <button
          onClick={() => startVerification({
            applicant: { email: user.email, external_id: user.id }
          })}
          disabled={isLoading}
        >
          Verify Identity
        </button>
      );
    }
    ```
  </Tab>
</Tabs>

## Callback Token Verification

Always verify the callback token server-side before granting access:

```bash theme={null}
curl -X POST https://verilock.io/api/v1/auth-engine/verify-token \
  -H "Authorization: Bearer qi_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIs..."
  }'
```

Response:

```json theme={null}
{
  "valid": true,
  "session_id": "ses_a1b2c3d4e5f6",
  "status": "approved",
  "risk_score": 12,
  "applicant": {
    "email": "user@example.com",
    "external_id": "usr_12345"
  },
  "verified_at": "2026-03-15T14:30:00Z",
  "profile": "standard"
}
```

<Warning>
  Never trust the callback parameters alone. Always verify the token via the API to prevent tampering.
</Warning>

## Liveness Detection

When using the **Standard** or **Enhanced** profile, liveness detection is automatically included. The verification flow captures a short video sequence to confirm the user is physically present.

| Liveness Mode | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| **Passive**   | AI-based analysis of a single selfie (no user action required) |
| **Active**    | User performs head movements or reads a code on screen         |

Configure the liveness mode in **Dashboard > Verification Profiles**.

## Auto-Redirect

When `autoRedirect` is enabled, users are automatically sent to the Verilock hosted flow without an intermediate step. After verification, they return to your callback URL.

| Setting        | Description                       | Default     |
| -------------- | --------------------------------- | ----------- |
| `autoRedirect` | Skip intermediate page            | `true`      |
| `modalMode`    | Open in modal instead of redirect | `false`     |
| `language`     | Force a specific locale           | Auto-detect |

<Tip>
  Use `modalMode` for single-page applications where a full redirect would disrupt the user experience.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid callback URL">
    The callback URL must exactly match the URL registered in the dashboard, including the protocol and path. Query parameters are allowed but the base URL must match.
  </Accordion>

  <Accordion title="Token verification fails">
    Tokens expire after 5 minutes. Ensure your server verifies the token immediately upon receiving the callback. Check that your API key is valid and has Auth Engine permissions.
  </Accordion>

  <Accordion title="CORS errors">
    Add your application's domain to the **Allowed Origins** list in the Auth Engine configuration. Include both the protocol and port if applicable.
  </Accordion>
</AccordionGroup>