The multi-factor authentication (MFA) API can be used to add additional factors of authentication to existing authentication strategies.
The API currently supports both time-based one-time passwords (TOTP) and SMS factors.
An object representing an Authentication Factor.
const factor = { object: 'authentication_factor', id: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ', createdAt: '2022-02-15T15:14:19.392Z', updatedAt: '2022-02-15T15:14:19.392Z', type: 'totp', totp: { qrCode: 'data:image/png;base64,{base64EncodedPng}', secret: 'NAGCCFS3EYRB422HNAKAKY3XDUORMSRF', uri: 'otpauth://totp/FooCorp:alan.turing@example.com?secret=NAGCCFS3EYRB422HNAKAKY3XDUORMSRF&issuer=FooCorp', }, };
interface FactorAn object representing a Challenge of an Authentication Factor.
const challenge = { object: 'authentication_challenge', id: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5', createdAt: '2022-02-15T15:26:53.274Z', updatedAt: '2022-02-15T15:26:53.274Z', expiresAt: '2022-02-15T15:36:53.279Z', authenticationFactorId: 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ', };
interface ChallengeEnrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const factor = await workos.mfa.enrollFactor({ type: 'totp', issuer: 'Foo Corp', user: 'alan.turing@example.com', });
Creates a Challenge for an Authentication Factor.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const challenge = await workos.mfa.challengeFactor({ authenticationFactorId: 'auth_factor_01FZ4TS14D1PHFNZ9GF6YD8M1F', smsTemplate: 'Your code is {{code}}', });
Verify Authentication Challenge.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const { challenge, valid } = await workos.mfa.verifyChallenge({ authenticationChallengeId: 'auth_challenge_01FVYZWQTZQ5VB6BC5MPG2EYC5', code: '123456', });
mfaParameters objectReturns objectGets an Authentication Factor.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const factor = await workos.mfa.getFactor( 'auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ', );
Permanently deletes an Authentication Factor. It cannot be undone.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.mfa.deleteFactor('auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ');
mfaParameters