Configure MFA for an Application

This guide walks through configuring multi-factor authentication for one of your applications: setting the policy, tuning the "remember this device" duration, and verifying the change.

For background on how MFA works in Aero2, see Multi-Factor Authentication.

Prerequisites

• An existing application (see Creating an Application)
• A dashboard session with the apps:write permission on the application
• The application's subdomain (e.g. acme.aero2.dev) or your dashboard URL

Settings Reference

MFA is controlled by two fields on the application's settings:

Both are merged into the application's settings JSON; only the fields you send are updated.

Update via the Dashboard API

# Make MFA optional and let trusted devices skip the challenge for 14 days
curl -X PUT https://dashboard.aero2.dev/api/applications/settings \
  -H "Cookie: <dashboard_session>" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_policy": "optional",
    "mfa_remember_device_days": 14
  }'

# Read the current settings back
curl https://dashboard.aero2.dev/api/applications/settings \
  -H "Cookie: <dashboard_session>"

The endpoint returns the full normalized settings object on success. Invalid values (e.g. an unknown policy or mfa_remember_device_days outside 0–365) return 400 with a details array.

Choosing a Policy

• off — MFA setup endpoints return 403. Use this when you want to disable MFA entirely (for example, while a frontend integration is incomplete).
• optional — Users opt in from their profile. This is the most common choice for a new app: existing users keep working, security-conscious users get protection.
• required — Existing users without MFA receive a restricted mfa_setup_required session on next login that only allows enrolling in MFA. New users must complete enrollment before reaching the app. Switch to this once your support team is ready to help users who lose authenticator access.

Switching from required back to optional does not disable any user's existing MFA — it only stops blocking users who haven't enrolled.

Disabling Remember-Device

Setting mfa_remember_device_days to 0 causes Aero2 to ignore any existing device-trust cookies and re-challenge every login. Existing rows in mfa_trusted_devices remain in the table but are no longer honored — they will expire on their own.

curl -X PUT https://dashboard.aero2.dev/api/applications/settings \
  -H "Cookie: <dashboard_session>" \
  -H "Content-Type: application/json" \
  -d '{"mfa_remember_device_days": 0}'

Verifying the Change

1. Sign in to the app as a user who has MFA enabled (or who needs to enroll, when policy is required).

2. Confirm the expected challenge or mfa_setup_required redirect occurs.

3. Check the audit log for an app_updated event with settings_changes containing the fields you sent:

   curl "https://dashboard.aero2.dev/api/audit?event_type=app_updated&limit=5" \
     -H "Cookie: <dashboard_session>"

Common Pitfalls

• Calling from an app subdomain. /api/applications/settings only accepts requests from the dashboard context. Calls from acme.aero2.dev are rejected.
• Forgetting Content-Type. Aero2's validator rejects bodies without application/json.
• Setting required before any user has enrolled. This is supported, but every existing user lands on the MFA setup screen on their next login — communicate the change ahead of time.