BioAuth integration guide

BioAuth is the product; FaceIn.id LLC is the service provider. This public guide covers application integration only. Customer-specific recovery, liveness, and authorization configuration is supplied through approved onboarding.

Access and compatibility

Request access at https://pieauth.id/developers/apply. Approved developers manage applications at https://dashboard.pieauth.id/login/. Keep using the existing application origin during enrollment.

This guide covers @pieauth/sdk version 0.2.5. Obtain the package version and registry access approved for your account during onboarding; availability can differ by account.

Existing FaceIn identifiers are compatibility names. Do not rename imports, methods, hosts, or stored identifiers merely to match the BioAuth brand. The portal's bundled browser client is a separate compatibility build, not the full current package.

Application setup

Register the application's exact permitted origins through the developer dashboard. Use only an application publishable key in browser configuration. Secret keys and privileged operations belong on your server. Obtain configuration through your approved account, not from examples or another application's page source.

The package exports FaceIn and FaceInError. The React entry point is @pieauth/sdk/react, exporting FaceInProvider and useFaceIn.

Construct a FaceIn client with the approved publishable apiKey. The configuration supports an environment and an approved baseUrl; use the deployment values supplied during onboarding. Do not redirect existing credentials to a new relying-party origin without a supported migration.

Sign-in integration

The core client supports these application methods:

Method	Integration purpose
`prepareAuthenticate(userId)`	Prepare an existing-user authentication before the user taps.
`authenticate(userId)`	Authenticate that user through supported device UI.
`prepareEnroll(userId)`	Prepare approved enrollment before the user taps.
`enroll(userId)`	Enroll a supported authenticator.
`prepare(userId)` and `signIn(userId)`	Combined sign-in/enrollment convenience flow; use only where automatic enrollment is appropriate.
`getToken()`	Read the client's current session token, if present.
`logout()`	Clear the client session.
`cancel()` and `destroy()`	Cancel work and release client resources.

Call the intended preparation method before the click handler. Invoke the corresponding authentication method directly from the user's gesture; do not insert unrelated asynchronous work before device authentication. Avoid preparing conflicting ceremonies for the same user. Handle cancelled, expired, and failed requests without granting access.

An application's own admission or approval policy is still required. A convenience enrollment flow is not evidence that a developer account has been approved.

Server verification and authorization

Treat browser state as UI state, not authorization. getTokenPayload() decodes data; it does not verify a signature. isAuthenticated() is not a substitute for server validation.

Your server must validate the supported session or authorization result using the current approved verification contract, enforce its application and user scope, and reject expired or invalid results. Do not log tokens or include them in URLs. Do not infer transaction authority from successful sign-in alone.

Credential management

listCredentials() and revokeCredential(credentialId) are supported client methods. Browser operations require the authenticated user's own session and are restricted to that user. Cross-user administration requires the approved server-side configuration and authorization; a publishable key alone is not sufficient.

Receipts and human authorization

BioAuth's supported authorization workflows can produce signed evidence for a configured action. Authentication, human presence, and authority to execute an action are distinct checks.

Before accepting a receipt, use the released verification contract to validate authenticity and current status, enforce scope and expiry, and associate it with the intended action. Retain and protect receipts according to your agreement and retention policy.

@pieauth/sdk version 0.2.5 does not export a general-purpose verifyReceipt method. Before enabling receipt-based actions, obtain the verification contract approved for your service version, including delivery, storage, revocation handling, and supported agent workflows. Keep receipt-dependent actions disabled until that integration is available and validated.

Recovery and liveness

Use the approved account-recovery experience and customer configuration. Do not build alternate reset or administrator-bypass paths from undocumented behavior.

Liveness availability depends on the supported platform, released version, and account policy. Mock providers and development examples do not establish production human presence. Never treat a missing, failed, or expired check as approval.

Integration checklist

Confirm package version, allowed origins, and account approval.
Exercise supported enrollment and returning-user sign-in on target devices.
Validate sessions on your server and enforce application permissions.
Exercise cancellation, expiry, denied access, and sign-out.
Confirm receipt verification and retention requirements before enabling protected actions.
Use private onboarding materials for customer-specific configuration.

Before production use, complete end-to-end enrollment, sign-in, and authorization checks with your approved account on each supported target device.