Add FACEIO to Your Login Page

Add facial authentication to an existing web login page with a clear enrollment path, the fio.js widget, backend account handling, and a fallback route for account recovery.

Back to Knowledge Center
By FACEIO Engineering Team Updated

A Practical Login Page Integration Flow

FACEIO can be added to a standard login page without replacing your existing account system. Keep enrollment, authentication, and backend account handling as separate steps.

Use the browser widget for camera capture, liveness checks, PIN prompts, and user interaction, but keep final access decisions on your backend. This keeps the developer experience straightforward while preserving a clear authentication boundary.

This tutorial assumes you already have a working login page. If you are starting from scratch, begin with the getting started guide to create your FACEIO application and get the public App ID from the FACEIO Console ↗.

Implementation Steps

Follow these steps to add FACEIO to an existing login page. Each step links to the relevant reference when you need more detail:

  1. Create a FACEIO application. Open the FACEIO Console, create a new application, and copy the public App ID. This public identifier is used by fio.js in the browser.
  2. Load the fio.js SDK. Add the fio.js script tag to your login and enrollment pages. Load it only where face capture is needed, not site-wide.
  3. Enroll new users. After account creation (and consent), call enroll() to capture the user's face and create a Facial ID. Store the Facial ID reference against the user's account on your backend.
  4. Authenticate returning users. Call authenticate() when the user chooses face login or when your app requires facial step-up verification. The SDK returns a result payload to the browser.
  5. Complete login on the backend. Send the returned Facial ID and required context to your backend, map it to the expected account, and apply your session and authorization rules. Use CHECKFACIALID only when you need to confirm that the Facial ID remains registered.
  6. Handle errors and fallback. Catch the fio.js error codes and offer retry guidance or a fallback login path (password, OTP, or support).

What to Put on the Login Page

For New Users

Present facial enrollment as an optional or required setup step after account creation, depending on your product policy. Show a consent notice before the camera prompt and link to your privacy information.

For Returning Users

Offer face authentication beside or instead of the password form. Label it clearly (“Sign in with face”) and keep fallback recovery available for camera and permission issues.

For the UX patterns behind these choices, read the face recognition login best practices guide. For the full launch path, including privacy notices, consent, and rollout planning, use the launch checklist and the privacy best practices.

Backend Account and Session Pattern

The browser callback from authenticate() returns an authentication result. Your backend remains responsible for selecting the account and issuing the session:

  1. Receive the authentication result and required request context at an endpoint on your server.
  2. Look up the user account mapped to the returned Facial ID, not a client-supplied user ID.
  3. Check the account status, tenant, requested action, and any other controls required by your application.
  4. Issue a short-lived session token bound to that user.
  5. Log the event timestamp, Facial ID, application ID, and outcome for audit without retaining verification media, face captures, or biometrics hashes.

The API checklist, REST API reference, webhook documentation, and security best practices guide cover these controls in detail. Do not let client-side state select an account or grant access by itself.

Developer Resources for Login Integration

Use the FACEIO documentation to implement the login-page flow, connect Facial IDs to account records, receive webhook events, and configure application settings.

Getting Started Set up your FACEIO app and collect the identifiers needed by your web project. Integration Guide Wire enrollment and authentication into your existing login page. Developer Guides Connect authentication results to backend account and recovery flows. REST API Manage Facial IDs, payloads, PIN codes, deletion, and backend checks. Webhooks Receive server-side events for enrollment and authentication workflows. FACEIO Console Create your App ID and manage login-page authentication settings.

Frequently Asked Questions

Do I need to remove my existing password login?

No. FACEIO can run alongside your existing login. Offer face as an alternative sign-in option, or as a step-up factor for sensitive actions. Keep your password fallback during the transition. See biometric login for web apps for the UX patterns.

How long does it take to add FACEIO to a login page?

The client-side integration is short, especially if you follow the getting started guide. Production readiness also depends on backend account and session handling, error handling, account recovery, consent text, and rollout testing, which are covered by the launch checklist.

What frameworks does fio.js support?

fio.js works with vanilla JavaScript, React, Vue, Angular, Next.js, Nuxt, Svelte, and Ember. See the integration guide for framework-specific notes.

How do I handle a user who loses camera access?

Keep a fallback login path such as password, OTP, or support escalation. Do not make face authentication the only way back into an account without a documented recovery path. The login best practices guide covers this in detail.

Related Guides

Add Face Login to Your Site Today

Your backend maps the returned Facial ID to an account and decides whether to issue a session. Pair this tutorial with the security best practices, privacy best practices, and the implementation checklist. Create an app in the FACEIO Console and test the complete flow in your own environment.

Open FACEIO Console Get Started