1. Docs
  2. Multi-Factor Auth

Multi-Factor Authentication

Add a second authentication factor for your identities, enforced per Environment.

Overview

Multi-factor authentication (MFA) requires an identity to present a second factor, beyond their password, when they sign in. In Canopy, MFA is configured per Environment, so you can require it in production while leaving staging open, and it applies the same way whether your users authenticate through the hosted login pages or the Direct API.

Per-Environment enforcement

Four settings, scoped to each Environment

Every Environment carries its own MFA policy:

mfa_required: whether identities in this Environment must use MFA.mfa_grace_period_days: how long a newly-required identity can keep signing in before they're forced to enroll.mfa_trusted_device_days: how long a verified device is remembered before it's challenged again.mfa_factor_allowlist: which factor types are permitted in this Environment.

Factor types

Canopy supports four factor types:

Authenticator app (TOTP): a time-based 6-digit code from an app like Google Authenticator or 1Password.Passkeys & security keys (WebAuthn): phishing-resistant FIDO2 credentials: device passkeys or hardware keys.Email OTP: a one-time code sent to the identity's verified email address.Recovery codes: single-use backup codes for when a primary factor isn't available.

Login-time decisions

At sign-in, Canopy returns one of five MFA decisions so your integration knows what to do next:

none: no MFA step is needed; continue signing in.challenge_required: the identity has a factor enrolled; prompt them to verify it.grace_pending: MFA is required but the grace window is still open; the user may proceed and is nudged to enroll.enrollment_required: MFA is required, the grace window has closed, and no factor is enrolled; the user must enroll before continuing.trusted_device: this device was remembered within the trusted-device window; the challenge is skipped.

Step-up & admin reset

Two operational behaviors round out the flow:

In-session step-up: sensitive operations (such as managing your own security settings) re-challenge for a factor even within an active session.Admin force-reset: an admin can clear an identity's enrolled factors to recover a lost-device lockout, forcing fresh enrollment on the next sign-in.

Where MFA applies

MFA covers both the Direct API and Hosted OAuth

The hosted login pages run the same challenge and enrollment flow as the Direct API, so your users are covered however they sign in. Tokens issued after a factor is verified record it in the standard amr (authentication methods reference) claim: for example ["pwd", "mfa"] for a password login plus a second factor, or ["sso", "mfa"] for an SSO step-up, so your backend can confirm a session was MFA-verified before allowing a sensitive action.

Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy