# Two-Factor Authentication

Two-factor authentication (2FA) adds a second verification step beyond your password when accessing the Fluxis Dashboard. Some sensitive actions—such as **creating API keys**—require an active 2FA method.

## Dashboard access

Manage 2FA at:

**`/app/user/2fa`**

From this page you can enroll methods, complete verification challenges, and remove methods you no longer use.

## Supported methods

| Method | Description |
| ------ | ----------- |
| **Email OTP** | One-time code sent to your registered email |
| **TOTP** | Time-based codes from an authenticator app (Google Authenticator, Authy, etc.) |
| **Passkey** | WebAuthn / FIDO2 hardware or platform keys |

::::note
A Google OAuth enrollment endpoint exists in the codebase but is not exposed in the dashboard UI today. Use Email OTP, TOTP, or Passkey.
::::

## Enrollment flow

Each method follows a two-step pattern:

1. **Begin enrollment** — start registration and receive setup data (QR code for TOTP, WebAuthn challenge for passkey, or OTP send for email)
2. **Verify enrollment** — confirm with a valid code or passkey assertion to activate the method

### Email OTP

1. POST enrollment begin → OTP sent to your email
2. Enter the code to finish enrollment

### TOTP (authenticator app)

1. POST enrollment begin → receive secret / QR code
2. Scan with your authenticator app
3. POST verify with a generated 6-digit code

### Passkey

1. POST register begin → browser WebAuthn prompt
2. POST register finish with the credential response

## Using 2FA for protected actions

Sensitive dashboard operations require a verified 2FA session:

1. **Create challenge** — request a challenge for a specific action (e.g. API key creation)
2. **Verify** — submit your OTP, TOTP code, or passkey assertion
3. **Complete action** — proceed within the verified session window

API key creation at `/app/api-keys` uses the `Require2FA()` middleware—without a enrolled method, you cannot create new keys.

::::warning
Enroll at least one 2FA method before attempting to create API credentials. See [API Credentials](/docs/developers/api-credentials).
::::

## Managing methods

| Action | Description |
| ------ | ----------- |
| List available methods | Methods your organization supports |
| List enrolled methods | Methods active on your account |
| Delete method | Remove a method by ID |

Keep at least one active method to avoid locking yourself out of protected dashboard features.

## Password management

From `/app/user`, you can also:

- View your profile (`GET /user/me`)
- Change password (`PUT /user/change-password`)
- Set initial password (`PUT /user/set-password`)

These endpoints require dashboard session authentication but not necessarily a fresh 2FA challenge unless policy requires it.

## Security recommendations

1. **Enroll TOTP or passkey** — more resistant to email compromise than OTP alone
2. **Register a backup method** — e.g. TOTP + passkey, so one lost device does not block access
3. **Do not share OTP codes** — Fluxis support will never ask for your 2FA code
4. **Review enrolled methods** — remove methods tied to lost devices promptly

## API vs dashboard authentication

::::info
2FA applies to **Dashboard (collaborator) sessions** only. REST API authentication uses API key + secret → Bearer token and does not involve 2FA on each API call.
::::

Integrations authenticate with [API Credentials](/docs/developers/api-credentials); team members authenticate to the dashboard with email, password, and 2FA.

## Related documentation

- [API Credentials](/docs/developers/api-credentials) — key creation requires 2FA
- [Team & Roles](/docs/developers/team-and-roles) — collaborator access levels
- [Sign Up](/docs/merchant-integration/sign-up) — initial onboarding