Interface GoTrueMFAApi

Contains the full multi-factor authentication API.

Hierarchy

GoTrueMFAApi

Index

Properties

webauthn

Methods

challenge challengeAndVerify enroll getAuthenticatorAssuranceLevel listFactors unenroll verify

Properties

webauthn

webauthn: WebAuthnApi

Methods

challenge

challenge(params: {
    factorId: string;
}): Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "totp"; expires_at: number; };
    error: null;
}>
Prepares a challenge used to verify that a user has access to a MFA factor.
Parameters
- params: {
  factorId: string;
  }
  - factorId: string
    
    ID of the factor to be challenged. Returned in enroll().
Returns Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "totp"; expires_at: number; };
    error: null;
}>
- Defined in src/lib/types.ts:1163
challenge(params: {
    channel: "sms" | "whatsapp";
    factorId: string;
}): Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "phone"; expires_at: number; };
    error: null;
}>
Parameters
- params: {
  channel: "sms" | "whatsapp";
  factorId: string;
  }
  - channel: "sms" | "whatsapp"
    
    Messaging channel to use (e.g. whatsapp or sms). Only relevant for phone factors
  - factorId: string
    
    ID of the factor to be challenged. Returned in enroll().
Returns Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "phone"; expires_at: number; };
    error: null;
}>
- Defined in src/lib/types.ts:1164
challenge(params: {
    factorId: string;
    webauthn: {
        rpId: string;
        rpOrigins?: string[];
    };
}): Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "webauthn"; expires_at: number; webauthn: { type: "create"; credential_options: { publicKey: PublicKeyCredentialCreationOptionsFuture; }; } | { ...; }; };
    error: null;
}>
Parameters
- params: {
      factorId: string;
      webauthn: {
          rpId: string;
          rpOrigins?: string[];
      };
  }
  - factorId: string
    
    ID of the factor to be challenged. Returned in enroll().
  - webauthn: {
    rpId: string;
    rpOrigins?: string[];
    }
    - rpId: string
      
      Relying party ID
    - Optional rpOrigins?: string[]
      
      Relying party origins
Returns Promise<{
    data: null;
    error: AuthError;
} | {
    data: { id: string; type: "webauthn"; expires_at: number; webauthn: { type: "create"; credential_options: { publicKey: PublicKeyCredentialCreationOptionsFuture; }; } | { ...; }; };
    error: null;
}>
- Defined in src/lib/types.ts:1165
challenge(params: MFAChallengeParams): Promise<AuthMFAChallengeResponse>
Parameters
- params: MFAChallengeParams
Returns Promise<AuthMFAChallengeResponse>
- Defined in src/lib/types.ts:1166

challengeAndVerify

challengeAndVerify(params: {
code: string;
factorId: string;
}): Promise<AuthMFAVerifyResponse>
Helper method which creates a challenge and immediately uses the given code to verify against it thereafter. The verification code is provided by the user by entering a code seen in their authenticator app.
Parameters
- params: {
  code: string;
  factorId: string;
  }
  - code: string
    
    Verification code provided by the user.
  - factorId: string
    
    ID of the factor being verified. Returned in enroll().
Returns Promise<AuthMFAVerifyResponse>
- Defined in src/lib/types.ts:1187

enroll

enroll(params: {
    factorType: "totp";
    friendlyName?: string;
    issuer?: string;
}): Promise<AuthMFAEnrollTOTPResponse>
Starts the enrollment process for a new Multi-Factor Authentication (MFA) factor. This method creates a new unverified factor. To verify a factor, present the QR code or secret to the user and ask them to add it to their authenticator app. The user has to enter the code from their authenticator app to verify it.

Upon verifying a factor, all other sessions are logged out and the current session's authenticator level is promoted to aal2.
Parameters
- params: {
      factorType: "totp";
      friendlyName?: string;
      issuer?: string;
  }
  - factorType: "totp"
    
    The type of factor being enrolled.
  - Optional friendlyName?: string
    
    Human readable name assigned to the factor.
  - Optional issuer?: string
    
    Domain which the user is enrolled with.
Returns Promise<AuthMFAEnrollTOTPResponse>
- Defined in src/lib/types.ts:1154
enroll(params: {
    factorType: "phone";
    friendlyName?: string;
    phone: string;
}): Promise<AuthMFAEnrollPhoneResponse>
Parameters
- params: {
      factorType: "phone";
      friendlyName?: string;
      phone: string;
  }
  - factorType: "phone"
    
    The type of factor being enrolled.
  - Optional friendlyName?: string
    
    Human readable name assigned to the factor.
  - phone: string
    
    Phone number associated with a factor. Number should conform to E.164 format
Returns Promise<AuthMFAEnrollPhoneResponse>
- Defined in src/lib/types.ts:1155
enroll(params: {
factorType: "webauthn";
friendlyName?: string;
}): Promise<AuthMFAEnrollWebauthnResponse>
Parameters
- params: {
  factorType: "webauthn";
  friendlyName?: string;
  }
  - factorType: "webauthn"
    
    The type of factor being enrolled.
  - Optional friendlyName?: string
    
    Human readable name assigned to the factor.
Returns Promise<AuthMFAEnrollWebauthnResponse>
- Defined in src/lib/types.ts:1156
enroll(params: MFAEnrollParams): Promise<AuthMFAEnrollResponse>
Parameters
- params: MFAEnrollParams
Returns Promise<AuthMFAEnrollResponse>
- Defined in src/lib/types.ts:1157

getAuthenticatorAssuranceLevel

getAuthenticatorAssuranceLevel(): Promise<AuthMFAGetAuthenticatorAssuranceLevelResponse>
Returns the Authenticator Assurance Level (AAL) for the active session.
- aal1 (or null) means that the user's identity has been verified only with a conventional login (email+password, OTP, magic link, social login, etc.).
- aal2 means that the user's identity has been verified both with a conventional login and at least one MFA factor.
Although this method returns a promise, it's fairly quick (microseconds) and rarely uses the network. You can use this to check whether the current user needs to be shown a screen to verify their MFA factors.
Returns Promise<AuthMFAGetAuthenticatorAssuranceLevelResponse>
- Defined in src/lib/types.ts:1212

listFactors

listFactors(): Promise<AuthMFAListFactorsResponse<readonly ["totp", "phone", "webauthn"]>>
Returns the list of MFA factors enabled for this user.

See
Returns Promise<AuthMFAListFactorsResponse<readonly ["totp", "phone", "webauthn"]>>
- Defined in src/lib/types.ts:1197

unenroll

unenroll(params: MFAUnenrollParams): Promise<AuthMFAUnenrollResponse>
Unenroll removes a MFA factor. A user has to have an aal2 authenticator level in order to unenroll a verified factor.
Parameters
- params: MFAUnenrollParams
Returns Promise<AuthMFAUnenrollResponse>
- Defined in src/lib/types.ts:1181

verify

verify(params: {
    challengeId: string;
    code: string;
    factorId: string;
}): Promise<AuthMFAVerifyResponse>
Verifies a code against a challenge. The verification code is provided by the user by entering a code seen in their authenticator app.
Parameters
- params: {
      challengeId: string;
      code: string;
      factorId: string;
  }
  - challengeId: string
    
    ID of the challenge being verified. Returned in challenge().
  - code: string
    
    Verification code provided by the user.
  - factorId: string
    
    ID of the factor being verified. Returned in enroll().
Returns Promise<AuthMFAVerifyResponse>
- Defined in src/lib/types.ts:1172
verify(params: {
    challengeId: string;
    code: string;
    factorId: string;
}): Promise<AuthMFAVerifyResponse>
Parameters
- params: {
      challengeId: string;
      code: string;
      factorId: string;
  }
  - challengeId: string
    
    ID of the challenge being verified. Returned in challenge().
  - code: string
    
    Verification code provided by the user.
  - factorId: string
    
    ID of the factor being verified. Returned in enroll().
Returns Promise<AuthMFAVerifyResponse>
- Defined in src/lib/types.ts:1173
verify(params: {
    challengeId: string;
    factorId: string;
    webauthn: MFAVerifyWebauthnParamFieldsBase & MFAVerifyWebauthnCredentialParamFields<"create" | "request">;
}): Promise<AuthMFAVerifyResponse>
Parameters
- params: {
      challengeId: string;
      factorId: string;
      webauthn: MFAVerifyWebauthnParamFieldsBase & MFAVerifyWebauthnCredentialParamFields<"create" | "request">;
  }
  - challengeId: string
    
    ID of the challenge being verified. Returned in challenge().
  - factorId: string
    
    ID of the factor being verified. Returned in enroll().
  - webauthn: MFAVerifyWebauthnParamFieldsBase & MFAVerifyWebauthnCredentialParamFields<"create" | "request">
Returns Promise<AuthMFAVerifyResponse>
- Defined in src/lib/types.ts:1174
verify(params: MFAVerifyParams): Promise<AuthMFAVerifyResponse>
Parameters
- params: MFAVerifyParams
Returns Promise<AuthMFAVerifyResponse>
- Defined in src/lib/types.ts:1175

Interface GoTrueMFAApi

Hierarchy

Index

Properties

Methods

Properties

webauthn

Methods

challenge

Parameters

params: { factorId: string; }

factorId: string

Returns Promise<{ data: null; error: AuthError; } | { data: { id: string; type: "totp"; expires_at: number; }; error: null; }>

Parameters

params: { channel: "sms" | "whatsapp"; factorId: string; }

channel: "sms" | "whatsapp"

factorId: string

Returns Promise<{ data: null; error: AuthError; } | { data: { id: string; type: "phone"; expires_at: number; }; error: null; }>

Parameters

params: { factorId: string; webauthn: { rpId: string; rpOrigins?: string[]; }; }

factorId: string

webauthn: { rpId: string; rpOrigins?: string[]; }

rpId: string

Optional rpOrigins?: string[]

Returns Promise<{ data: null; error: AuthError; } | { data: { id: string; type: "webauthn"; expires_at: number; webauthn: { type: "create"; credential_options: { publicKey: PublicKeyCredentialCreationOptionsFuture; }; } | { ...; }; }; error: null; }>

Parameters

params: MFAChallengeParams

Returns Promise<AuthMFAChallengeResponse>

challengeAndVerify

Parameters

params: { code: string; factorId: string; }

code: string

factorId: string

Returns Promise<AuthMFAVerifyResponse>

enroll

Parameters

params: { factorType: "totp"; friendlyName?: string; issuer?: string; }

factorType: "totp"

Optional friendlyName?: string

Optional issuer?: string

Returns Promise<AuthMFAEnrollTOTPResponse>

Parameters

params: { factorType: "phone"; friendlyName?: string; phone: string; }

factorType: "phone"

Optional friendlyName?: string

phone: string

Returns Promise<AuthMFAEnrollPhoneResponse>

Parameters

params: { factorType: "webauthn"; friendlyName?: string; }

factorType: "webauthn"

Optional friendlyName?: string

Returns Promise<AuthMFAEnrollWebauthnResponse>

Parameters

params: MFAEnrollParams

Returns Promise<AuthMFAEnrollResponse>

getAuthenticatorAssuranceLevel

Returns Promise<AuthMFAGetAuthenticatorAssuranceLevelResponse>

listFactors

See

Returns Promise<AuthMFAListFactorsResponse<readonly ["totp", "phone", "webauthn"]>>

unenroll

Parameters

params: MFAUnenrollParams

Returns Promise<AuthMFAUnenrollResponse>

verify

Parameters

params: { challengeId: string; code: string; factorId: string; }

challengeId: string

code: string

factorId: string

Returns Promise<AuthMFAVerifyResponse>

Parameters

params: { challengeId: string; code: string; factorId: string; }

challengeId: string

code: string

factorId: string

Returns Promise<AuthMFAVerifyResponse>

Parameters

params: { challengeId: string; factorId: string; webauthn: MFAVerifyWebauthnParamFieldsBase & MFAVerifyWebauthnCredentialParamFields<"create" | "request">; }

challengeId: string

params: {
factorId: string;
}

Returns Promise<{
data: null;
error: AuthError;
} | {
data: { id: string; type: "totp"; expires_at: number; };
error: null;
}>

params: {
channel: "sms" | "whatsapp";
factorId: string;
}

Returns Promise<{
data: null;
error: AuthError;
} | {
data: { id: string; type: "phone"; expires_at: number; };
error: null;
}>

params: {
factorId: string;
webauthn: {
rpId: string;
rpOrigins?: string[];
};
}

webauthn: {
rpId: string;
rpOrigins?: string[];
}

`Optional` rpOrigins?: string[]

Returns Promise<{
data: null;
error: AuthError;
} | {
data: { id: string; type: "webauthn"; expires_at: number; webauthn: { type: "create"; credential_options: { publicKey: PublicKeyCredentialCreationOptionsFuture; }; } | { ...; }; };
error: null;
}>

params: {
code: string;
factorId: string;
}

params: {
factorType: "totp";
friendlyName?: string;
issuer?: string;
}

`Optional` friendlyName?: string

`Optional` issuer?: string

params: {
factorType: "phone";
friendlyName?: string;
phone: string;
}

`Optional` friendlyName?: string

params: {
factorType: "webauthn";
friendlyName?: string;
}

`Optional` friendlyName?: string

params: {
challengeId: string;
code: string;
factorId: string;
}

params: {
challengeId: string;
code: string;
factorId: string;
}

params: {
challengeId: string;
factorId: string;
webauthn: MFAVerifyWebauthnParamFieldsBase & MFAVerifyWebauthnCredentialParamFields<"create" | "request">;
}