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-verify
    client-id="your-client-id"
    theme='{"mode":"dark"}'
    locale="en"
></fivucsas-verify>

Quick Start

Basic Usage

JavaScript

// Initialize the auth widget
const auth = new FivucsasAuth({
  clientId: 'your-oauth-client-id'
});

// Start the verification flow — verify() resolves to an AuthResult.
// There is no onSuccess/onError constructor callback.
try {
  const result = await auth.verify({ container: '#auth-container' });
  console.log('Authentication successful', result.accessToken);
  console.log('User:', result.userId, result.email);
} catch (error) {
  console.error('Authentication failed', error.message);
}

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',
        theme: { mode: 'dark' }
      });
      auth.verify({ container: containerRef.current }).then((result) => {
        // Handle successful verification (resolved AuthResult)
        console.log('Verified:', result);
      });
    };
    document.body.appendChild(script);

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

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

Constructor Options

Pass these options when creating a new FivucsasAuth instance. There are no onSuccess/onError constructor callbacks — success is the resolved value of verify() (see Methods). container, redirectUri, scope, methods and onCancel are passed to verify(options), not the constructor.

Option	Type	Description
clientId*	string	Your OAuth 2.0 client ID, obtained from your tenant admin console.
theme	object	Widget theme object, e.g. `{ mode: "light" }` or `{ mode: "dark" }`. As a Web Component attribute pass JSON: `theme='{"mode":"dark"}'`. Defaults to `{ mode: "light" }`.
locale	string	Language code: `"en"` or `"tr"`. Defaults to `"en"`.

Methods

`verify(options)`

Starts the verification flow. Opens the widget UI and guides the user through the configured authentication steps. Accepts per-call options (container, redirectUri, scope, methods, onCancel). Resolves to an AuthResult on success; there is no constructor-level onSuccess callback.

The resolved AuthResult has shape { success, sessionId, userId, email, displayName, completedMethods, accessToken, refreshToken, idToken, expiresIn } — note there are no token, user, or expiresAt fields.

JavaScript

// Returns a Promise<AuthResult>
const result = await auth.verify({ container: '#auth-container' });

`destroy()`

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

JavaScript

auth.destroy();

`loginRedirect(options)`

Initiates the hosted-first redirective OIDC flow: the user is sent to verify.fivucsas.com/login, completes MFA, then returns to your redirectUri with ?code=…&state=… for token exchange.

`handleRedirectCallback()`

Call on your redirect-URI page to complete the hosted OIDC flow. Validates state and resolves the returned authorization code.

Events

The element dispatches hyphenated CustomEvents on the container. (The colon-namespaced forms — fivucsas:ready etc. — are internal SDK↔iframe postMessage types and are never dispatched on the container.)

fivucsas-step-change

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

fivucsas-complete

Fired on successful authentication. Detail: the AuthResult ({ success, sessionId, userId, email, displayName, completedMethods, accessToken, refreshToken, idToken, expiresIn }).

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-complete', (e) => {
  const { accessToken } = e.detail;
  // Send token to your backend for validation
  fetch('/api/login', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
});

container.addEventListener('fivucsas-step-change', (e) => {
  console.log(`Step ${e.detail.progress}/${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/api/v1/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