FIVUCSAS Auth Widget SDK

Embed identity verification and authentication into any web application with a single script tag. The widget handles the complete verification flow including face recognition, liveness detection, and multi-factor authentication.

Installation

Script Tag (Recommended)

HTML

<script src="https://verify.fivucsas.com/fivucsas-auth.js"></script>

Web Component

HTML

<fivucsas-auth
    client-id="your-client-id"
    theme="dark"
    lang="en"
></fivucsas-auth>

Quick Start

Basic Usage

JavaScript

// Initialize the auth widget
const auth = new FivucsasAuth({
  clientId: 'your-oauth-client-id',
  container: '#auth-container',
  onSuccess: (result) => {
    console.log('Authentication successful', result.token);
    console.log('User:', result.user);
  },
  onError: (error) => {
    console.error('Authentication failed', error.message);
  }
});

// Start the verification flow
auth.verify();

React Integration

React (JSX)

import { useEffect, useRef } from 'react';

function AuthWidget() {
  const containerRef = useRef(null);

  useEffect(() => {
    // Load the SDK script
    const script = document.createElement('script');
    script.src = 'https://verify.fivucsas.com/fivucsas-auth.js';
    script.onload = () => {
      const auth = new window.FivucsasAuth({
        clientId: 'your-client-id',
        container: containerRef.current,
        theme: 'dark',
        onSuccess: (result) => {
          // Handle successful verification
          console.log('Verified:', result);
        }
      });
      auth.verify();
    };
    document.body.appendChild(script);

    return () => document.body.removeChild(script);
  }, []);

  return <div ref={containerRef} />;
}

Constructor Options

Pass these options when creating a new FivucsasAuth instance.

Option	Type	Description
clientId*	string	Your OAuth 2.0 client ID, obtained from the FIVUCSAS developer portal.
container*	string \| Element	CSS selector or DOM element where the widget will be rendered.
onSuccess	function	Callback invoked on successful authentication. Receives `{ token, user, expiresAt }`.
onError	function	Callback invoked on authentication failure. Receives `{ code, message }`.
onCancel	function	Callback invoked when the user cancels the verification flow.
theme	string	Widget theme: `"light"` or `"dark"`. Defaults to `"light"`.
lang	string	Language code: `"en"` or `"tr"`. Defaults to browser locale.
redirectUri	string	OAuth 2.0 redirect URI. Must match a registered URI for the client.
scope	string	OAuth 2.0 scopes, space-separated. Defaults to `"openid profile"`.
methods	string[]	Allowed auth methods: `"face"`, `"voice"`, `"fingerprint"`, `"webauthn"`, `"nfc"`.

Methods

`verify()`

Starts the verification flow. Opens the widget UI and guides the user through the configured authentication steps.

JavaScript

auth.verify();
// Returns a Promise<AuthResult>
// Can also be used with async/await:
const result = await auth.verify();

`destroy()`

Removes the widget from the DOM and cleans up event listeners. Call this when unmounting the component.

JavaScript

auth.destroy();

`setTheme(theme)`

Dynamically switch the widget theme between "light" and "dark".

`setLang(lang)`

Change the widget language at runtime. Supported: "en", "tr".

Events

The widget emits custom DOM events on the container element. You can listen for these in addition to (or instead of) the callback options.

fivucsas:ready

Fired when the widget is fully loaded and ready to start verification.

fivucsas:step

Fired when the user advances to a new verification step. Detail: { step, total, method }.

fivucsas:success

Fired on successful authentication. Detail: { token, user, expiresAt }.

fivucsas:error

Fired on authentication failure. Detail: { code, message }.

fivucsas:cancel

Fired when the user cancels the verification flow.

Event Listener Example

JavaScript

const container = document.getElementById('auth-container');

container.addEventListener('fivucsas:success', (e) => {
  const { token, user } = e.detail;
  // Send token to your backend for validation
  fetch('/api/login', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` }
  });
});

container.addEventListener('fivucsas:step', (e) => {
  console.log(`Step ${e.detail.step}/${e.detail.total}: ${e.detail.method}`);
});

Error Codes

Code	Meaning	Resolution
INVALID_CLIENT	Client ID not found	Check your clientId matches the registered OAuth app.
CAMERA_DENIED	Camera permission denied	Prompt user to allow camera access for face verification.
LIVENESS_FAILED	Liveness check failed	User may retry. Ensure good lighting and a clear face.
SESSION_EXPIRED	Verification session timed out	Call `verify()` again to start a new session.
NETWORK_ERROR	Network connectivity issue	Check internet connection and retry.
SERVER_ERROR	Server-side error	Retry later or contact support.

Security Best Practices

Always validate the returned token on your backend by calling the FIVUCSAS token introspection or userinfo endpoint. Never trust client-side verification alone.

Server-side validation (Node.js)

// Validate the token server-side
const response = await fetch('https://api.fivucsas.com/oauth2/userinfo', {
  headers: { 'Authorization': `Bearer ${token}` }
});

if (!response.ok) {
  throw new Error('Invalid token');
}

const user = await response.json();
// user.sub = user ID
// user.email = verified email
// user.name = display name