> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Staff security settings: MFA, passkeys, and app-lock

> Manage staff MFA (TOTP and WebAuthn passkeys), app-lock policy, and biometric unlock from /settings/security, with links to security monitoring.

Staff security settings page at `/settings/security`. Authenticated staff use it to manage multi-factor authentication (TOTP and WebAuthn passkeys), app-lock policy, and biometric authentication preferences.

## Overview

The Security settings page surfaces `MfaEnrollment` for managing MFA factors (TOTP authenticator and WebAuthn passkeys) and `AppLockSettingsSection` for configuring idle-lock policy, PIN setup, and biometric enrollment. State is sourced from `useAppLockContext`. Permission-gated cards at the bottom of the page link staff with `pf.security_events.view` to Security Events and Security Alerts. The route has no explicit `RequirePermission` guard — standard platform authentication is sufficient.

## Who it's for

Access follows your organization's role and module configuration. Requires an active platform staff session.

## Before you start

* You must be signed in to the platform.
* A TOTP authenticator app (for example, Google Authenticator, 1Password, Authy) is required for TOTP enrollment.
* For passkeys, you need a browser and device that support WebAuthn (most modern desktop and mobile browsers; iOS Safari in standalone PWA mode is not supported and the option is hidden there).
* Passkeys must be enabled for your project in **Supabase Dashboard → Auth → MFA**. If the toggle is off, enrollment fails with "Could not add passkey."

## Steps

### Enroll a TOTP authenticator

1. Navigate to `/settings/security`.
2. In the **MFA** section, select **Enable MFA**.
3. Scan the QR code with your authenticator app, or enter the secret manually.
4. Enter the 6-digit code from your app to verify and activate the factor.

### Add a passkey

1. In the **MFA** section, select **Add a passkey**.
2. (Optional) Enter a friendly name (for example, "Work laptop", "iPhone"). If you leave it blank, the default name is used.
3. Complete the browser's WebAuthn prompt (Touch ID, Face ID, Windows Hello, security key, or platform passkey).
4. The new passkey appears in the factor list with status **verified**.

You can enroll multiple passkeys (one per device or authenticator) alongside a TOTP factor.

### Remove an MFA factor

1. In the factor list, locate the TOTP authenticator or passkey you want to remove.
2. Select **Remove** next to that factor and confirm in the dialog.

<Warning>
  Removing your last MFA factor disables MFA on the account. If your organization requires MFA, re-enroll a factor immediately.
</Warning>

### Sign in with MFA

When MFA is enabled, after entering your password you see the MFA challenge:

* If you have a TOTP factor, enter the 6-digit code from your authenticator app.
* If you have a verified passkey, select **Use a passkey** and complete the WebAuthn prompt.
* Both options appear together when both factor types exist. If your browser does not support WebAuthn and you have no TOTP factor, the page shows a "no usable second factor" message — sign in from a supported browser to recover access.

### Configure app-lock

1. In the **App Lock** section, set your idle-lock policy and optionally set up a PIN or biometric method.
2. Use the linked cards to navigate to Security Events or Security Alert Configuration (requires `pf.security_events.view`).

## Key concepts

**TOTP factor** — A time-based one-time password generated by an authenticator app. One TOTP factor per account.

**Passkey (WebAuthn) factor** — A device-bound credential verified with the device's biometric or PIN. Enrollment runs the full WebAuthn ceremony through Supabase-managed MFA (`auth.mfa.webauthn`); no shared secret leaves the device. You can have multiple verified passkeys.

**Friendly name** — A label you choose during passkey enrollment so you can identify the device later (for example, "Work MacBook").

**App-lock policy** — Controls how quickly the app locks after inactivity and which unlock methods are available (PIN, biometric).

**Biometric enrollment** — Enables fingerprint or face-based app-lock unlock where the device supports it. This is separate from passkey MFA, which gates sign-in rather than the in-session lock.

## Example: enroll a passkey

```text theme={null}
1. Open /settings/security.
2. MFA section → Add a passkey.
3. Name it "MacBook Touch ID" → Continue.
4. Approve the browser's WebAuthn prompt with Touch ID.
5. Factor list now shows: TOTP (verified), MacBook Touch ID (verified).
6. Next sign-in: enter password → choose "Use a passkey" → Touch ID → signed in.
```

## Related

<Columns cols={2}>
  <Card title="Platform Foundation" icon="layer-group" href="/pf/overview">
    Platform Foundation overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/platform.tsx
  * src/platform/settings/SecuritySettingsPage.tsx
  * src/platform/auth/app-lock/AppLockContext.tsx
  * src/platform/auth/components/MfaEnrollment.tsx
  * src/platform/auth/components/MfaChallenge.tsx
  * src/platform/auth/components/webauthn-mfa.ts
</Accordion>