Developer Center fio.js, API & Webhooks

Docs for adding facial authentication to your website or web app: load fio.js, use enroll() for first-time registration and authenticate() for returning-user sign-in, then connect REST API endpoints and webhooks when your backend needs them.

Jump to: Quick Start Integration Guide REST API Webhooks
OPEN FACEIO Console

Create an application in the FACEIO Console, copy its Public ID, configure your domains and security options, then add fio.js to your website or web app.

Quick Start - Facial Authentication

~ 5 mins

1 Create Your Application

Sign in to the FACEIO Console ↗ and use the Application Wizard to create an app. Choose a recognition engine, add the domains where the widget may run, and copy the Public ID shown at the end.

A Public ID looks like fioa1b2c3d4. It is safe to use in the browser and is required when you create the SDK instance.

2 Import fio.js to Your Site

Add the widget container and load fio.js before the closing </body> tag. Use the official CDN so browser-side fixes and security updates reach your app without a redeploy.

index.html
HTML 
<div id="faceio-modal"></div>
<script src="https://cdn.faceio.net/fio.js"></script>
Using a bundler? Install the official NPM package ↗
npm i @faceio/fiojs

3 Instantiate a faceIO Object

Create one faceIO instance with your app's Public ID. Keep that instance available to the parts of your UI that need to enroll or authenticate a user.

app.js
JavaScript 
<script type="text/javascript">
  /* Instantiate fio.js with your application's Public ID */
  const faceio = new faceIO("app-public-id");
</script>

4 Invoke the Widget

Once fio.js is loaded and the faceIO() instance exists, call one of the two main methods:

enroll()

Registers a new user via face recognition. The passwordless equivalent of a traditional sign-up. Access Documentation →

authenticate()

Authenticates a returning, previously enrolled user via face recognition. The passwordless equivalent of a traditional sign-in. Access Documentation →

app.js
JavaScript 
<button onclick="enrollNewUser()">Enroll New User</button>
<button onclick="authenticateUser()">Authenticate User</button>

<script type="text/javascript">
  const faceio = new faceIO("app-public-id");

  function enrollNewUser() {
    // Calling faceio.enroll() triggers the enrollment flow
  }

  function authenticateUser() {
    // Calling faceio.authenticate() triggers the authentication flow
  }

  function handleError(errCode) {
    // Handle error here
  }
</script>

What's next

Full Getting Started Guide

Console setup, screenshots & launch checklist

SDK & Framework Guides

Examples for React, Vue, Angular & vanilla JS

Security & Best Practices

Checks to make before production rollout

SDK & Frameworks

Get Started Icon
Quickstart

Getting Started Guide

A practical walkthrough for your first FACEIO integration: console setup, domain allowlisting, engine selection, and a working enrollment flow, with screenshots along the way.

  • Step-by-step console walkthrough with screenshots
  • Checklist for domains, keys, and browser permissions
  • Starter HTML you can adapt to your app
Open Setup Guide
Developer Code Icon
API Docs

API Reference & Boilerplate

The fio.js SDK reference for method parameters, return values, error codes, and framework examples.

  • Full enroll() & authenticate() method reference
  • All error codes with recommended handling patterns
  • Framework examples for common JavaScript stacks
View Integration Guide
Vanilla JavaScript

Vanilla JS

Plain JavaScript
React

React

v18+ / Hooks
Vue.js

Vue.js

Vue 3 / Composition
Angular

Angular

v15+ / Standalone
Next.js

Next.js

App & Pages Router
Svelte

Svelte

SvelteKit ready
Nuxt.js

Nuxt.js

Nuxt 3 / SSR
Ember.js

Ember.js

Octane edition
Framework Compatibility Notes
  • Framework-neutral SDK
    Use FACEIO with React, Vue, Angular, Next.js, Svelte, Nuxt.js, Ember.js, or plain JavaScript.
  • Use existing routes
    fio.js is framework-neutral. Add it to the sign-up and sign-in flows already used by your website or web app.
  • Browser requirements
    Runs in modern browsers with a standard webcam. Users do not need dedicated biometric hardware.
Browser Support:
Chrome Chrome
Firefox Firefox
Edge Edge
+ all Chromium-based browsers
View all examples

Webhooks & API

When a user enrolls, authenticates, or deletes a Facial ID, FACEIO sends an HTTP POST to your configured endpoint with the event details in the JSON body.

Full Docs
Webhooks Icon
Real-Time Events

Webhooks & Event Notifications

Keep your backend in sync when users enroll, authenticate, or delete a Facial ID.

ENROLL AUTH DELETION
Configure Webhooks

How Webhooks Work

  1. 1

    A user completes an enrollment, authentication, or deletion flow in the FACEIO widget.

  2. 2

    FACEIO sends an HTTP POST to your configured endpoint URL.

  3. 3

    Validate the WWW-Authenticate bearer token before processing the JSON payload.

  4. Return 200 OK within 6 seconds so FACEIO knows the event was received.

Setup guide (5 steps)
webhook-payload.json
JSON 
{
  "eventName": "AUTH",
  "facialId": "fid_a1b2c3d4e5f6...",
  "appId": "your-app-public-id",
  "clientIp": "203.0.113.42",
  "payload": "your-linked-user-data",
  "details": {
    "timestamp": "2025-12-29",
    "gender": "male",
    "age": "28"
  }
}

Key Fields

eventName
Event type: ENROLL / AUTH / DELETION
facialId
Application-scoped Facial ID
payload
Your linked user data (Business plan+)
clientIp
Public IP of the user's browser
Authenticate incoming requests

Always compare the WWW-Authenticate bearer token with the webhook key shown in the FACEIO Console before trusting the payload.

REST API Endpoints

HTTP Globe Icon

Access REST API Endpoints

Programmatic Control

Use authenticated HTTPS endpoints to manage FACEIO applications, Facial IDs, and server-side account workflows. fio.js runs in the browser and is not required on your backend.

GET POST DELETE Manage apps and Facial IDs
Explore REST API
DELETE
Delete Facial ID

Remove a user's Facial ID from your application's facial index.
GET
Get App Details

Retrieve metadata, enrollment counts, and configuration for an application.
GET
List All Applications

List the FACEIO applications linked to your account, including IDs, names, and status.
POST
Check Membership

Check whether a Facial ID belongs to your application's facial index.
POST
Switch Engine Tier

Programmatically switch between facial recognition engine tiers for your app.
View All Endpoints

Full REST API reference

Run FACEIO on your own infrastructure?

Use the on-premise option if your deployment needs local infrastructure and local control of the selected recognition engine.

Learn More

Error Codes

When enroll() or authenticate() rejects, the promise includes a numeric errCode. Handle the common cases explicitly so users get a clear next step.

Code Constant Meaning Recommended Action
1 fioErrCode.PERMISSION_REFUSED Camera or microphone access was denied by the user or browser. Prompt the user to allow camera access and retry.
2 fioErrCode.NO_FACES_DETECTED No face was detected within the camera frame during the session. Ask the user to ensure good lighting and face the camera directly.
3 fioErrCode.UNRECOGNIZED_FACE The scanned face does not match any enrolled user in your app's facial index. Show an error and offer the enroll flow if the user is new.
4 fioErrCode.MANY_FACES Multiple faces were detected simultaneously in the camera frame. Ask the user to ensure only their face is visible.
5 fioErrCode.FACE_DUPLICATION This face is already enrolled in your application's facial index. Redirect the user to the login (authenticate) flow instead.
6 fioErrCode.PAD_ATTACK Liveness detection flagged a spoofing attempt (photo, video, or mask). Reject the attempt without exposing details about the detection logic.
7 fioErrCode.MINORS_NOT_ALLOWED Age estimation indicates the user is under the minimum age threshold set in your app config. Display an appropriate age-gate message and abort the flow.
10 fioErrCode.NETWORK_IO A network error or timeout occurred communicating with FACEIO servers. Retry after a short delay; check the user's connectivity.

This table covers common cases. The full reference includes network, session, browser, and consent-related errors.

Full Error Code Reference

Best Practices

Read before going to production

Facial authentication needs a careful rollout. Start with security best practices and privacy & consent handling before you ship.

Security Icon
Required setup

Application Security

Restrict where the widget can run, keep the default PIN Code validation enabled, configure liveness detection, and validate backend events.

  • Allowlist domains for exact production origins
  • Configure liveness detection to help detect presentation attacks
  • Validate webhook tokens before updating account state
View Security Guidelines
Privacy Icon
Privacy controls

Application Privacy

Show clear consent before capture, keep payloads small, honor deletion requests, and leave an audit trail your team can review.

  • Always show consent before capture
  • Minimize payload data to strict necessities
  • Honor valid erasure requests under your applicable retention rules
View Privacy Guidelines
Facial ID
Identity model

Unique Facial Identifier

After enrollment, FACEIO returns a Facial ID that belongs to your application. Store that identifier next to your own user record.

// Example mapping
await db.users.update({
  where: { email: "user@x.com" },
  data:  { facialId: u.facialId }
});
Learn About Facial IDs
Trust Center
Data flow

Recognition Engine & Data Flow

FACEIO, including fio.js, the Widget, REST API, and Console, does not store, handle, or access biometric hashes. The facial recognition engine selected by the application owner handles facial matching and biometric hashes. Application owners remain responsible for consent, retention, deletion, and engine configuration.

Consent
User deletion
Engine choice
Scoped IDs
Visit Trust Center

Production Checklist

Do

  • Load fio.js exclusively from cdn.faceio.net
  • Restrict widget to your exact production domains in the Console
  • Validate webhook tokens and expected application identifiers before updating account state
  • Use HTTPS on all pages where the widget is loaded
  • Show a consent screen before calling enroll()

Don't

  • Do not load fio.js from unofficial mirrors; use the official CDN so browser-side fixes reach your app
  • Do not store face images, biometric hashes, or sensitive authentication payloads in client-side storage or application logs
  • Do not load the widget on http://; camera access and secure browser APIs require HTTPS
  • Do not call enroll() before presenting the required notice and obtaining explicit end-user consent
  • Never expose your API secret key on the client side

Products Overview

Facial Authentication

Add facial authentication with fio.js. Users enroll in the browser, and your app receives an application-scoped facialId for future authentication flows.

  • Store the returned facialId in your backend to link FACEIO enrollment to your own user record.
  • Use enroll() for first-time facial registration in your application, then authenticate() when the enrolled user returns to sign in.
  • Use it for passwordless sign-in, account re-authentication, or step-up checks in your existing access flow.
fio.js facial recognition login face authentication
Integration Guide

Meeting Shield

A Chrome extension for deepfake detection in Google Meet, Zoom Web, and Microsoft Teams Web. Use it to alert participants to suspected synthetic, replayed, or manipulated video in browser-based meetings.

Explore Meeting Shield

ID Match

An embeddable browser widget for ID capture, live selfie capture, liveness checks, and selfie-to-ID portrait matching. Optional document-field extraction is powered by PixLab DOCSCAN ↗, which supports 11K+ ID document formats from over 197 countries and territories. ID Match does not authenticate the document or establish legal identity.

Explore ID Match

Resources & Community

FACEIO Console

FACEIO Console

Create applications, review metrics, adjust security settings, and copy the keys your integration needs.

Use the console during development to manage allowed domains, choose recognition settings, and confirm that each environment is using the right Public ID.

Live Metrics App Config API Keys
Open Console

FAQ

Common questions

Help Center

Troubleshooting

Status

Live uptime
Developer setup

Add Facial Authentication to Your Website or Web App

Create an application in the Console, copy your Public ID, load fio.js, and test enroll() and authenticate() with your backend.

5 minutes straightforward integration
fio.js, REST API, and webhook references
Framework-neutral browser integration
Consent, deletion, and security checks
Open FACEIO Console Read Setup Guide