Face Authentication API Checklist for Production

Use this developer checklist to connect FACEIO authentication events to your backend, validate results securely, and avoid trusting client-side state alone.

Back to Knowledge Center
By FACEIO Engineering Team Updated

Client Widget First, Backend Decision Always

FACEIO handles the browser authentication flow, but access control should not end in JavaScript. Your backend should map the returned Facial ID to the expected account, validate its own account and request context, and decide what level of access to grant.

The fio.js SDK runs camera capture, liveness checks, and face authentication in the browser. It returns a result to your frontend code. That result is a client-side signal, not the final authorization decision. The browser is user-controlled, so any client-side value can be inspected, modified, or replayed. The trust decision belongs on your server.

This checklist focuses on the API and security decisions around facial authentication for web applications. For the UI flow, start with the integration guide. For the broader API positioning, see the Face Authentication API overview.

Server-Side Authentication Checklist

Every authentication event must pass through these checks on your server before a session is issued:

  • Keep private API keys out of frontend code, mobile bundles, and public repositories. Use the public App ID in the browser; the API key stays server-side.
  • Use CHECKFACIALID from your backend when you need to confirm that a Facial ID is currently registered. This endpoint does not authenticate a specific browser callback.
  • Bind the result to the expected account, tenant, and application context. Do not accept a client-supplied user ID as authoritative.
  • Use PIN confirmation when your policy requires step-up verification. See Always Ask for PIN and SETFACIALIDPINCODE for policy and backend management.
  • Log successful and failed authentication events with enough context for security review without logging verification media, face captures, or biometrics hashes.
  • Define retry, fallback, lockout, and manual review rules for failed authentication checks.
  • Rate-limit authentication attempts per IP and per Facial ID to reduce repeated capture attempts and automated abuse.

Session Binding & Token Issuance

After your backend validates its account state and request context, it can issue a session. Bind that session to the account mapped from the returned Facial ID, not to an account identifier supplied by the browser:

Bind to the Facial ID

Look up the user account mapped to the returned Facial ID. Do not treat a user ID sent by the browser as authoritative.

Short-Lived Tokens

Issue short-lived session tokens. Require re-authentication (face or fallback) for step-up actions rather than relying on a long-lived session.

Audit Trail

Record the verification timestamp, Facial ID, App ID, and outcome. This trail helps your team review account access and support cases without storing verification media.

Common Integration Mistakes

Trusting Client State

Do not let a successful frontend callback select an account or grant access by itself. Map the Facial ID on your backend and apply your own session, tenant, and authorization rules.

Missing Session Binding

A successful authentication result still needs to map to the correct account and requested action. Bind the resulting session on your backend instead of accepting an account identifier from the browser.

No Operational Metrics

Track enrollment completion, authentication success, camera failures, retries, and support escalations. Without metrics you cannot tell a rollout problem from a product problem.

Exposing the API Key

The API key is a server-side secret. If it appears in frontend code, a public repo, or a mobile bundle, rotate it immediately in the FACEIO Console.

Developer Resources for API Integration

Use these FACEIO resources to set up fio.js, manage Facial IDs, configure webhooks, protect API keys, and prepare your account flow for production.

Getting Started Create an application and prepare the keys used by your integration. Integration Guide Implement the browser capture and authentication workflow. Developer Guides Use server-side validation and deployment guidance for production apps. REST API Manage Facial IDs, PIN codes, payloads, deletion, and backend checks. Webhooks Receive server-side events for enrollment, authentication, and account workflows. FACEIO Console Create apps, manage API settings, and prepare production rollout.

Frequently Asked Questions

How should my server handle the client-side authentication result?

The browser is user-controlled. Treat the fio.js result as input, map the returned Facial ID to the expected account on your backend, validate your account and request context, and then decide whether to issue a session. Use CHECKFACIALID when you need to confirm that a Facial ID is currently registered; it does not authenticate a specific browser callback.

Where should I store my FACEIO API key?

Store it server-side only, preferably in an environment variable or secret manager. Do not place it in frontend code, mobile bundles, or public repositories. The public App ID is safe in the browser; the API key is not.

What should I log from an authentication event?

Log the timestamp, Facial ID, outcome, application ID, and request context needed for review. Do not log verification media, face captures, or biometrics hashes. See the security best practices and privacy best practices guides.

How is the API checklist different from the launch checklist?

The launch checklist covers the full product rollout, including UX, consent, privacy, and rollout stages. This API checklist focuses on server-side account checks, session binding, API key handling, and security decisions after authentication.

Related Guides

Ship a Secure API Integration

For account authentication, continue with the FACEIO SDK flow, keep private API keys on your backend, map Facial IDs to your own accounts, and apply server-side session controls. For stateless image-to-image face matching, review the online face verification API.

Open FACEIO Console Open Developer Guides