API reference

const {
  initSdk,
  getDeviceBoundKeyId,
  webauthnCreateCred,
  webauthnGetCred,
  registerDeviceBoundCredential
} = window.com$thalesgroup$gemalto$fido2$web;

function initSdk(): Promise<void>

const initSdk = window.com$thalesgroup$gemalto$fido2$web.initSdk;

window.addEventListener('load', async () => {
  try {
    await initSdk();
    console.log('SDK initialized successfully');
  } catch (error) {
    console.error('Initialization failed:', error);
  }
});

interface DeviceBoundKeyInfo {
  dbkKid: string;    // The device-bound key identifier (base64url)
  dbkExist: boolean; // Whether a DBK keypair exists for this user on this browser
}

function getDeviceBoundKeyId(userIdBase64Url: string): Promise<DeviceBoundKeyInfo>

dbkKid = base64url(HMAC-SHA256(hmacKey, userId_bytes || rpId_bytes))

const getDeviceBoundKeyId = window.com$thalesgroup$gemalto$fido2$web.getDeviceBoundKeyId;

async function handleUserLogin(userIdB64Url) {
  const { dbkKid, dbkExist } = await getDeviceBoundKeyId(userIdB64Url);

  if (dbkExist) {
    // User has a registered DBK on this browser — proceed with FIDO authentication
    await authenticateWithFIDO(dbkKid);
  } else {
    // User has no DBK on this browser — show alternative authentication (OTP, etc.)
    await authenticateWith2FA(userIdB64Url, dbkKid);
  }
}

function base64urlEncode(str) {
  const bytes = new TextEncoder().encode(str);
  const base64 = btoa(String.fromCharCode(...bytes));
  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
}

const userIdB64Url = base64urlEncode('user123');
const { dbkKid, dbkExist } = await getDeviceBoundKeyId(userIdB64Url);

function webauthnCreateCred({
  options: APIModelServerPublicKeyCredentialCreationOptionsResponse,
  abortSignal?: AbortSignal
}): Promise<APIModelStandardAttestationServerPublicKeyCredential>

const webauthnCreateCred = window.com$thalesgroup$gemalto$fido2$web.webauthnCreateCred;

async function registerUser(userId) {
  // 1. Get attestation options from your Relying Party backend
  const response = await fetch('/api/rp/fido2/attestation/options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId })
  });
  const attestationOptions = await response.json();

  // 2. Create credential using the SDK
  const credential = await webauthnCreateCred({ options: attestationOptions });

  // 3. Send credential to your Relying Party backend
  const resultResponse = await fetch('/api/rp/fido2/attestation/result', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(credential)
  });
  return await resultResponse.json();
}

const controller = new AbortController();
setTimeout(() => controller.abort(), 60000); // Cancel after 60 seconds

try {
  const credential = await webauthnCreateCred({
    options: attestationOptions,
    abortSignal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Registration was cancelled');
  }
}

{
  "challenge": "base64url_encoded_challenge",
  "rp": { "id": "example.com", "name": "Example RP" },
  "user": {
    "id": "base64url_encoded_user_id",
    "name": "user@example.com",
    "displayName": "User Name"
  },
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -7 }
  ],
  "timeout": 60000,
  "extensions": {
    "thalesgroup_dbk_ext": {
      "v": 1,
      "kid": "base64url_dbkkid",
      "allowedAlgorithms": [-7]
    }
  }
}

{
  "id": "base64url_credential_id",
  "rawId": "base64url_raw_credential_id",
  "type": "public-key",
  "response": {
    "clientDataJSON": "base64url_client_data",
    "attestationObject": "base64url_attestation_object"
  },
  "authenticatorAttachment": "platform",
  "clientExtensionResults": {
    "thalesgroup_dbk_ext": {
      "v": 1,
      "pk": {
        "kid": "base64url_dbkkid",
        "kty": "EC",
        "crv": "P-256",
        "x": "base64url_x",
        "y": "base64url_y"
      },
      "sig": "base64url_signature"
    }
  }
}

function webauthnGetCred({
  mediationRequirement?: CredentialMediationRequirement,
  options: APIModelServerPublicKeyCredentialGetOptionsResponse,
  abortSignal?: AbortSignal,
  userIdB64Url?: string
}): Promise<APIModelStandardAssertionServerPublicKeyCredential>

const webauthnGetCred = window.com$thalesgroup$gemalto$fido2$web.webauthnGetCred;

async function authenticateUser() {
  const response = await fetch('/api/rp/fido2/assertion/options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  const assertionOptions = await response.json();

  const credential = await webauthnGetCred({ options: assertionOptions });

  const resultResponse = await fetch('/api/rp/fido2/assertion/result', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(credential)
  });
  return await resultResponse.json();
}

const credential = await webauthnGetCred({
  mediationRequirement: 'conditional',
  options: assertionOptions
});

{
  "challenge": "base64url_encoded_challenge",
  "timeout": 60000,
  "rpId": "example.com",
  "allowCredentials": [
    { "type": "public-key", "id": "base64url_credential_id" }
  ],
  "userVerification": "required",
  "extensions": {
    "thalesgroup_dbk_ext": { "v": 1, "kid": "base64url_dbkkid" }
  }
}

{
  "id": "base64url_credential_id",
  "rawId": "base64url_raw_credential_id",
  "type": "public-key",
  "response": {
    "clientDataJSON": "base64url_client_data",
    "authenticatorData": "base64url_authenticator_data",
    "signature": "base64url_signature",
    "userHandle": "base64url_user_handle"
  },
  "authenticatorAttachment": "platform",
  "clientExtensionResults": {
    "thalesgroup_dbk_ext": {
      "v": 1,
      "sig": "base64url_dbk_signature",
      "kid": "base64url_dbkkid"
    }
  }
}

type FallbackConfirmationCallback = () => boolean | Promise<boolean>;

interface DualRequestOptions {
  assertionReq: APIModelServerPublicKeyCredentialGetOptionsResponse;
  attestationReq: APIModelServerPublicKeyCredentialCreationOptionsResponse;
  onFallbackConfirmation?: FallbackConfirmationCallback;
}

type RegisterDbkCredentialResult =
  | { type: 'assertion';   credential: APIModelStandardAssertionServerPublicKeyCredential }
  | { type: 'attestation'; credential: APIModelStandardAttestationServerPublicKeyCredential };

function registerDeviceBoundCredential(
  options: DualRequestOptions
): Promise<RegisterDbkCredentialResult>

const { registerDeviceBoundCredential } = window.com$thalesgroup$gemalto$fido2$web;

const result = await registerDeviceBoundCredential({
  assertionReq,
  attestationReq,
  onFallbackConfirmation: () => new Promise((resolve) => {
    showConfirmModal({
      message: 'Your passkey was not found on this browser. Register a new one?',
      onConfirm: () => resolve(true),
      onCancel:  () => resolve(false),
    });
  })
});

if (result.type === 'assertion') {
  await submitAssertionResult(result.credential);   // Path 2a
} else {
  await submitAttestationResult(result.credential); // Path 2b
}

type CredentialMediationRequirement =
  | 'silent'      // No user interaction — fails if not possible
  | 'optional'    // User may be prompted (default)
  | 'required'    // User must be prompted
  | 'conditional' // Autofill-assisted authentication

class Fido2WebSdkError extends Error {
  name: 'Fido2WebSdkError';
  code: string;       // e.g. 'DBK-0005'
  category: string;   // 'DBK', 'VAL', 'CONV', or 'WEB'
  shortDesc: string;  // Brief description
  details: string;    // Detailed message with context
}