Biometrics

Authenticate users with device biometrics (Face ID, Touch ID, fingerprint) and securely store credentials or arbitrary data in the device keychain.

Access: startiapp.Biometrics

For a step-by-step guide to implementing biometric login — see Biometric Login.

Methods

`scan(title?, reason?): Promise<boolean>`

Triggers a biometric scan (fingerprint or face recognition) and returns whether it succeeded.

Parameters:

Parameter	Type	Required	Default	Description
title	`string`	No	`"Prove you have fingers!"`	The title shown in the biometric prompt
reason	`string`	No	`"Can't let you in if you don't."`	The reason/subtitle shown in the prompt

Returns: Promise<boolean> —true if the scan was successful.

Example:

const success = await startiapp.Biometrics.scan(
  "Verify Identity",
  "Please authenticate to continue"
);

if (success) {
  console.log("Biometric scan passed");
}

`getAuthenticationType(): Promise<BiometricsAuthenticationType>`

Returns the type of biometric authentication available on the device.

Returns: Promise<BiometricsAuthenticationType> —"face", "fingerprint", or "none".

Example:

const type = await startiapp.Biometrics.getAuthenticationType();

if (type === "face") {
  console.log("Face ID available");
} else if (type === "fingerprint") {
  console.log("Fingerprint available");
} else {
  console.log("No biometrics available");
}

`checkAccess(): Promise<PermissionStatus>`

Checks the current permission status for biometrics on the device.

Returns: Promise<PermissionStatus> —Object with a granted boolean.

Example:

const status = await startiapp.Biometrics.checkAccess();

if (status.granted) {
  console.log("Biometrics access granted");
}

`setSecuredContent(content: unknown): Promise<void>`

Saves arbitrary content to the device's secure keychain storage. The content is JSON-serialized before storing.

Parameters:

Parameter	Type	Required	Description
content	`unknown`	Yes	The data to store (will be JSON-serialized)

Returns: Promise<void>

Example:

await startiapp.Biometrics.setSecuredContent({
  apiToken: "abc123",
  refreshToken: "xyz789",
});

`getSecuredContent<T>(title?, reason?): Promise<T | null>`

Retrieves previously stored secured content. Triggers a biometric scan to authorize access.

Parameters:

Parameter	Type	Required	Default	Description
title	`string`	No	`"Prove you have fingers!"`	The biometric prompt title
reason	`string`	No	`"Can't let you in if you don't."`	The biometric prompt reason

Returns: Promise<T | null> —The deserialized content, or null if nothing is stored or parsing fails.

Example:

interface Tokens {
  apiToken: string;
  refreshToken: string;
}

const tokens = await startiapp.Biometrics.getSecuredContent<Tokens>(
  "Access Tokens",
  "Authenticate to retrieve your saved tokens"
);

if (tokens) {
  console.log("API Token:", tokens.apiToken);
}

`hasSecuredContent(): Promise<boolean>`

Checks whether secured content exists in the keychain without triggering a biometric scan.

Returns: Promise<boolean> —true if secured content exists.

Example:

const hasContent = await startiapp.Biometrics.hasSecuredContent();

if (hasContent) {
  console.log("Secured content is stored");
}

`removeSecuredContent(): Promise<void>`

Removes the secured content from the keychain.

Returns: Promise<void>

Example:

await startiapp.Biometrics.removeSecuredContent();

`setUsernameAndPassword(username, password): Promise<void>`

Saves a username and password pair to the device's secure keychain.

Parameters:

Parameter	Type	Required	Description
username	`string`	Yes	The username to store
password	`string`	Yes	The password to store

Returns: Promise<void>

Example:

await startiapp.Biometrics.setUsernameAndPassword("john@example.com", "s3cret");

`getUsernameAndPassword(title?, reason?): Promise<{ username: string; password: string } | null>`

Retrieves the saved username and password. Triggers a biometric scan to authorize access.

Parameters:

Parameter	Type	Required	Default	Description
title	`string`	No	`"Prove you have fingers!"`	The biometric prompt title
reason	`string`	No	`"Can't let you in if you don't."`	The biometric prompt reason

Returns: Promise<{ username: string; password: string } | null> —The credentials, or null if none are stored.

Example:

const credentials = await startiapp.Biometrics.getUsernameAndPassword(
  "Login",
  "Authenticate to auto-fill your credentials"
);

if (credentials) {
  console.log("Username:", credentials.username);
  // Auto-fill the login form
  document.querySelector<HTMLInputElement>("#username")!.value = credentials.username;
  document.querySelector<HTMLInputElement>("#password")!.value = credentials.password;
}

`hasUsernameAndPassword(): Promise<boolean>`

Checks whether a username and password pair is stored without triggering a biometric scan.

Returns: Promise<boolean> —true if credentials are stored.

Example:

const hasCreds = await startiapp.Biometrics.hasUsernameAndPassword();

if (hasCreds) {
  console.log("Saved credentials available — show biometric login button");
}

`removeUsernameAndPassword(): Promise<void>`

Removes the saved username and password from the keychain.

Returns: Promise<void>

Example:

await startiapp.Biometrics.removeUsernameAndPassword();

`startSaveUsernameAndPassword(request): Promise<void>`

Begins the automatic credential capture flow. This attaches middleware to a login form's submit button that captures the username and password when the user submits the form.

After a successful login, call endSaveUsernameAndPassword() to finalize saving.

Parameters:

Parameter	Type	Required	Description
request	`SaveUsernameAndPasswordConfiguration`	Yes	Configuration for form selectors and localization

Returns: Promise<void>

Example:

await startiapp.Biometrics.startSaveUsernameAndPassword({
  usernameInputFieldSelector: "#username",
  passwordInputFieldSelector: "#password",
  submitButtonSelector: "#login-button",
  title: "Save Login",
  reason: "Save your credentials for quick login next time",
  language: "en",
});

`endSaveUsernameAndPassword(config?): Promise<void>`

Completes the credential capture flow. Call this after a successful login. It will prompt the user (if they have not previously consented) to save credentials using biometrics, then store them if the user agrees.

Parameters:

Parameter	Type	Required	Description
config	`EndSaveUsernameAndPasswordConfiguration`	No	Optional key to identify the configuration

Returns: Promise<void>

Example:

// After successful login
await startiapp.Biometrics.endSaveUsernameAndPassword();

Types

`BiometricsAuthenticationType`

type BiometricsAuthenticationType = "none" | "face" | "fingerprint";

`PermissionStatus`

interface PermissionStatus {
  granted: boolean;
}

`SaveUsernameAndPasswordConfiguration`

Full configuration for the automated credential capture flow. Combines form selectors with internationalization settings.

type SaveUsernameAndPasswordConfiguration = {
  key?: string;
} & SaveUsernameAndPasswordConfigurationSelectors &
  SaveUsernameAndPasswordI18n;

`SaveUsernameAndPasswordConfigurationSelectors`

type SaveUsernameAndPasswordConfigurationSelectors = {
  usernameInputFieldSelector: string;
  passwordInputFieldSelector: string;
  submitButtonSelector: string;
  executingButtonSelector?: string;
};

`SaveUsernameAndPasswordI18n`

Internationalization options for the biometric consent dialog. Provide one of three options:

A built-in language ("da" or "en")
A confirmMessageTemplate with optional biometrics type translations
Full custom translations

type SaveUsernameAndPasswordI18n = {
  title: string;
  reason: string;
} & (
  | { language?: "da" | "en" }
  | {
      confirmMessageTemplate: string;
      biometricsTypeTranslations?: {
        face: string;
        fingerprint: string;
      };
    }
  | {
      translations: {
        nextTime: {
          title: string;
          subtitle: string;
          acceptedButtonText: string;
          declinedButtonText: string;
        };
        biometricsType: {
          face: string;
          fingerprint: string;
        };
      };
    }
);

`EndSaveUsernameAndPasswordConfiguration`

type EndSaveUsernameAndPasswordConfiguration = {
  key?: string;
};

`BiometricsResultResponse`

type BiometricsResultResponse<T> = {
  key: string;
  result: T;
};

On this page