Fidar Web SDK

A browser-based JavaScript/TypeScript SDK for integrating Fidar Authentication into your web application. Supports QR Device Login, Passkey (WebAuthn) Registration, OIDC Login, Account & Wallet APIs, and Transaction Signing.

Features

• QR-based device login with optional Bluetooth proximity
• Access token and session management
• Account and profile APIs
• Wallet and transaction APIs
• Beneficiary listing
• Device management
• Tenant configuration
• Consistent, typed error handling

Installation

npm install fidar-web-sdk

yarn add fidar-web-sdk

Initialization

Use Fidar.init() to create an SDK instance. It pre-fetches tenant configuration on startup so it is available immediately before the first method call.

import { Fidar } from "fidar-web-sdk";

const fidar = await Fidar.init({
  auth: {
    realm: "your-realm",
    clientId: "your-client-id",
  },
});

Config reference

const fidar = await Fidar.init({
  apiBase: "https://app.fidar.io",  // optional — defaults to Fidar production
  auth: {
    realm: "your-realm",            // required
    clientId: "your-client-id",     // required
  },
});

Contact Fidar to obtain your realm and clientId credentials.

Authentication

QR Login

Starts a QR-based device login flow. The user scans the displayed QR code using the Fidar mobile app to authenticate.

const result = await fidar.loginWithDeviceQR(
  (status) => console.log("Status:", status),
  (qrBase64) => setQrImage(qrBase64)
);

// result: DeviceQRLoginResult
// { qrImage: string, deviceCode: string, accessToken: string }

Status values (DeviceQRFlowStatus):

| Status | Description | |---|---| | STARTING | Flow is initializing | | DEVICE_AUTH_STARTED | Device auth session created | | QR_READY | QR code is ready to display | | PENDING | Waiting for mobile app scan | | VERIFIED | User authenticated successfully | | EXPIRED | Session timed out | | ERROR | Flow failed |

Bind Device (Bluetooth Proximity + QR)

Runs the full device bind flow. If Bluetooth proximity is enabled for your tenant, it performs a proximity check before proceeding to QR login.

Must be called from a user gesture (e.g. a button click) for Bluetooth to work correctly.

const result = await fidar.bindDevice(
  (status) => console.log("Status:", status),
  (qrBase64) => setQrImage(qrBase64),
  "optional-customer-id"   // optional
);

Session

Get access token

const token = fidar.getAccessToken();

Check if authenticated

const loggedIn = fidar.isAuthenticated(); // boolean

Get user ID

const userId = fidar.getUserId(); // string

Logout

Ends the current session and clears all stored credentials.

fidar.logout();

Get realm

const realm = fidar.getRealm();

Get client ID

const clientId = fidar.getClientId();

Profile

Get logged-in user profile

const profile = await fidar.getMyProfile();

Accounts

Get account by customer ID

const account = await fidar.getAccountByCustomerId("customer-123");
// returns: AccountResponse

Wallets

Get wallets

const wallets = await fidar.getWallets();
// returns: WalletBalance[]

Transactions

Get transactions

const transactions = await fidar.getTransactions();
// returns: Transaction[]

Beneficiaries

List beneficiaries

const beneficiaries = await fidar.getBeneficiaries();
// returns: Beneficiary[]

Devices

Authorize device

await fidar.authorizeDevice();

Get my devices

const devices = await fidar.getMyDevices();

Transaction Signing (WebAuthn)

signChallenge signs a server-provided challenge using the user's registered passkey and returns a WebAuthn assertion object. The typical flow is:

1. Call your backend to initiate the signing session — it returns a challenge
2. Pass the challenge to signChallenge — the user is prompted for biometric/PIN confirmation
3. Stringify the assertion and send it back to your backend to complete the operation

// 1. Initiate signing on your backend
const { challenge, txnId } = await initiateSign({ userId, amount, toAccount });

// 2. Sign the challenge with the user's passkey
const assertion = await fidar.signChallenge(challenge);

// 3. Complete the operation on your backend
await transfer({
  txnId,
  assertionJson: JSON.stringify(assertion),
});

Notes:

• Requires WebAuthn support in the browser (navigator.credentials).
• userVerification is set to "required" — biometric or PIN confirmation is always prompted.

Tenant Configuration

Returns the cached tenant configuration fetched during Fidar.init(). If init() was not used, the config is fetched lazily on first use.

const config = fidar.getTenantConfig();
// returns: TenantConfig

Error Handling

All SDK methods throw a FidarException on failure. Use isFidarException to narrow the type and access structured error details.

import { isFidarException } from "fidar-web-sdk";

try {
  await fidar.getWallets();
} catch (err) {
  if (isFidarException(err)) {
    console.error(err.code, err.detail);
  }
}

Exported Types

// Data
WalletBalance
Transaction
Beneficiary
AccountResponse
LoginResult
TenantConfig

// QR / Device Auth
DeviceQRLoginResult
DeviceQRFlowStatus

// Errors
FidarErrorDetail
FidarErrorProps

License

UNLICENSED — This SDK is provided for authorized use only. You may not use, copy, modify, or redistribute it without explicit written authorization from Fidar.