Initiates an MFA challenge
Sends OTP via SMS, initiates push notification, or prepares for OTP entry
Challenge parameters including mfaToken
Challenge response with oobCode if applicable
If challenge initiation fails
const challenge = await mfa.challenge({
mfaToken: mfaTokenFromLogin,
challengeType: 'otp',
authenticatorId: 'otp|dev_xxx'
});
// User enters OTP from their authenticator app
const challenge = await mfa.challenge({
mfaToken: mfaTokenFromLogin,
challengeType: 'oob',
authenticatorId: 'sms|dev_xxx'
});
console.log(challenge.oobCode); // Use for verification
Enrolls a new MFA authenticator
Requires MFA access token with 'enroll' scope
Enrollment parameters including mfaToken and factorType
Enrollment response with authenticator details
If enrollment fails
const enrollment = await mfa.enroll({
mfaToken: mfaToken,
factorType: 'otp'
});
console.log(enrollment.secret); // Base32 secret
console.log(enrollment.barcodeUri); // QR code URI
const enrollment = await mfa.enroll({
mfaToken: mfaToken,
factorType: 'sms',
phoneNumber: '+12025551234'
});
Gets enrolled MFA authenticators filtered by challenge types from context.
Challenge types are automatically resolved from the stored MFA context (set when mfa_required error occurred).
MFA token from mfa_required error
Array of enrolled authenticators matching the challenge types
If the request fails or context not found
try {
await auth0.getTokenSilently();
} catch (e) {
if (e instanceof MfaRequiredError) {
// SDK automatically uses challenge types from error context
const authenticators = await auth0.mfa.getAuthenticators(e.mfa_token);
}
}
Gets available MFA enrollment factors from the stored context.
This method exposes the enrollment options from the mfa_required error's mfaRequirements.enroll array, eliminating the need for manual parsing.
MFA token from mfa_required error
Array of enrollment factors available for the user (empty array if no enrollment required)
If MFA context not found
try {
await auth0.getTokenSilently();
} catch (error) {
if (error.error === 'mfa_required') {
// Get enrollment options from SDK
const enrollOptions = await auth0.mfa.getEnrollmentFactors(error.mfa_token);
// [{ type: 'otp' }, { type: 'phone' }, { type: 'push-notification' }]
showEnrollmentOptions(enrollOptions);
}
}
try {
const factors = await auth0.mfa.getEnrollmentFactors(mfaToken);
if (factors.length > 0) {
// User needs to enroll in MFA
renderEnrollmentUI(factors);
} else {
// No enrollment required, proceed with challenge
}
} catch (error) {
if (error instanceof MfaEnrollmentFactorsError) {
console.error('Context not found:', error.error_description);
}
}
Verifies an MFA challenge and completes authentication
The scope and audience are retrieved from the stored context (set when the mfa_required error occurred). The grant_type is automatically inferred from which verification field is provided (otp, oobCode, or recoveryCode).
Verification parameters with OTP, OOB code, or recovery code
Token response with access_token, id_token, refresh_token
If verification fails (invalid code, expired, rate limited)
If MFA context not found
If grant_type cannot be inferred
Rate limits:
const tokens = await mfa.verify({
mfaToken: mfaTokenFromLogin,
otp: '123456'
});
console.log(tokens.access_token);
const tokens = await mfa.verify({
mfaToken: mfaTokenFromLogin,
oobCode: challenge.oobCode,
bindingCode: '123456' // Code user received via SMS
});
const tokens = await mfa.verify({
mfaToken: mfaTokenFromLogin,
recoveryCode: 'XXXX-XXXX-XXXX'
});
Client for Auth0 MFA API operations
Manages multi-factor authentication including:
This is a wrapper around auth0-auth-js MfaClient that maintains backward compatibility with the existing spa-js API.
MFA context (scope, audience) is stored internally keyed by mfaToken, enabling concurrent MFA flows without state conflicts.
Example