Multi-Factor API
Email and phone multi-factor methods are only available in a paid plan of FusionAuth. Please visit our pricing page to learn more about paid plans.
This API controls multi-factor authentication (MFA) options.
Authentication#
Some of these operations can use JWT authentication instead of API key authentication. In some cases, when you have a valid twoFactorId, neither a JWT nor an API key is required.
Learn more about JWT authentication and see examples here.
TOTP Implementation#
Support for Authy, Google Authenticator and other time based one-time password solutions are not premium features and are included in the Community plan.
While there is underlying support for different code lengths, algorithms and time steps, at the current time the system only allows for the following TOTP settings:
| Configuration setting | Currently allowed value |
|---|---|
authenticator.algorithm | HmacSHA1 |
authenticator.codeLength | 6 |
authenticator.timeStep | 30 |
Any attempt to change these configuration values will currently be ignored. If you need different configuration settings, please file a GitHub issue detailing your use case.
Use the following APIs to manage Multi-Factor authentication:
| Operation | Method | Endpoint |
|---|---|---|
| Enable Multi-Factor | POST | /api/user/two-factor/{userId}/api/user/two-factor |
| Disable Multi-Factor | DELETE | /api/user/two-factor/{userId}?code={code}&methodId={methodId}/api/user/two-factor/{userId}/api/user/two-factor/api/user/two-factor?code={code}&methodId={methodId} |
| Update Multi-Factor Method | PUT | /api/user/two-factor/{userId}?methodId={methodId} |
| Generate a Secret | GET | /api/two-factor/secret |
| Start Multi-Factor | POST | /api/two-factor/start |
| Retrieve Multi-Factor Status | GETPOST | /api/two-factor/status/{twoFactorTrustId}/api/two-factor/status |
| Send a Multi-Factor Code During Login or Step Up | POST | /api/two-factor/send/{twoFactorId} |
| Send a Multi-Factor Code When Enabling MFA | POST | /api/two-factor/send |
| Send a Multi-Factor Code When Disabling MFA | POST | /api/two-factor/send |
| Generate Recovery Codes | POST | /api/user/two-factor/recovery-code/{userId} |
| Retrieve Recovery Codes | GET | /api/user/two-factor/recovery-code/{userId} |