List of hooks in WP 2FA

WP 2FA has a number of settings that allow website administrators to configure the plugin as they wish. However, in some cases, administrators and developers might want to change some of the plugin’s behavior that cannot be changed via a setting. While this does not happen often, due to the nature of how WordPress websites are used, there might be edge cases in which this is needed.

In such cases one can use hooks in the WP 2FA plugin to hook into the plugin’s functionality and modify its behavior. Below is a list of hooks and parameters found in the WP 2FA plugin.

Note: if you would like us to add a hook send us an email at [email protected] with all the details and requirements.

wp_2fa_custom_setup_page_link

Important: use this hook only if the user(s) do not have access to the WordPress dashboard. If the users have access to the WordPress dashboard use the hook wp_2fa_setup_page_link.

Function

Use this hook to specify the page where a user should be redirected to when required to setup 2FA based on your own logic, for example if a user belongs to a certain group of roles etc. By default the plugin does a great job of handling where to take users when setting up 2FA, however, this might be required in certain custom setups.

Parameters

• $url – the URL where the user should be redirected to
• $user – the user object of the user that needs to be redirected

Example code

add_filter( 'wp_2fa_custom_setup_page_link', 'my_custom_setup_page_link', 10, 2 );
function my_custom_setup_page_link( $url, $user ) {
    if ( in_array( 'author', (array) $user->roles ) ) {
         // The user has the "author" role.
        $url = ‘my-custom-slug’;
    }
    return $url;
}

wp_2fa_mail_default_settings

Function

The filter provides just a single argument, $default_settings, which contains the default list of strings used within the plugin which can be read, altered, and returned back to our plugin prior to display.

Parameters

• $default_settings – Array of default strings used throughout emails.

Example code

add_filter( 'wp_2fa_mail_default_settings', 'my_custom_email_strings' );
function my_custom_email_strings( $default_settings ) {
    $default_settings['login_code_setup_email_body'] = '<p>Hello world</p>';
    return $default_settings;
}

wp_2fa_oob_redirect_url

Function

Use this hook to redirect the user to a different URL when sending an Out-Of-Band email (2FA authentication method that sends a link via email).

Parameters

• $redirect – The URL you would like to redirect the user to
• $user – The user object of the user that needs to be redirected

Example code

function change_redirect( string $redirect, \WP_User $user ) {
     $redirect = 'https://melapress.com?id=" . $user->ID;
     return $redirect;
}

wp_2fa_replacement_email_strings

Function

In the plugin’s emails you can use tags such as {user_login_name} and {grace_period} which are replaced with applicable strings when an email is generated and sent to a user. This filter allows you to set your own replacements or add your own tags.

Parameters

•  $replacements – Array of default strings used throughout emails.

Example code

add_filter( 'wp_2fa_mail_default_settings', 'my_custom_replacement_reconfigure_strings' );
function my_custom_replacement_reconfigure_strings( $replacements ) {
    $replacements['grace_period'] = '<p>Hello world</p>';
    return $replacements;
}

wp_2fa_replacement_reconfigure_strings

Function

In the plugin’s reconfiguration email’s you can use tags such as {reconfigure_or_configure} and {reconfigure_or_configure_capitalized} which are replaced with applicable strings when an email is generated and sent to a user. This filter allows you to set your own replacements or add your own tags.

Parameters

•  $replacements – Array of default strings used throughout emails.

Example code

add_filter( 'wp_2fa_mail_default_settings', 'my_custom_replacement_reconfigure_strings' );
function my_custom_replacement_reconfigure_strings( $replacements ) {
    $replacements['reconfigure_or_configure'] = '<p>Hello world</p>';
    return $replacements;
}

wp_2fa_setup_page_link

Important: use this hook only if the user has access to the WordPress dashboard. If you are using a custom front-end 2FA page use the hook wp_2fa_custom_setup_page_link.

Function

Use this hook to specify the page where a user should be redirected to when required to setup 2FA based on your own logic, for example if a user belongs to a certain group of roles etc. By default the plugin does a great job of handling where to take users when setting up 2FA, however, this might be required in certain custom setups.

Parameters

• $url – the URL where the user should be redirected to

Example code

add_filter( 'wp_2fa_setup_page_link', 'my_custom_setup_page_link', 10, 1 );
function my_custom_setup_page_link( $url ) {
    $user = wp_get_current_user();
    if ( in_array( 'author', (array) $user->roles ) ) {
         // The user has the "author" role.
        $url = ‘my-custom-slug’;
    }
    return $url;
}

wp_2fa_should_redirect_unconfigured

Function

Use this filter to control whether the plugin intercepts and blocks backend requests when a user is forced to set up two-factor authentication but has not yet completed the configuration. By default the filter returns true, meaning the plugin will intercept backend requests and redirect the user to the 2FA setup page, ensuring they cannot bypass the setup requirement.

Parameters

bool – true by default, meaning the user will be redirected to the 2FA setup page. Return false to allow backend requests to pass through.

By returning false, you can suppress this behavior, allowing backend requests to pass through without being intercepted by the plugin. This is useful when third-party plugins such as WooCommerce, or custom implementations rely on specific backend requests that need to complete even while a user is in the forced 2FA setup state.

Example code

// Allow all backend requests to pass through during forced 2FA setup
add_filter( 'wp_2fa_should_redirect_unconfigured', '__return_false' );

wp_2fa_user_is_unlocked

Function

This action is fired after a user has been unlocked. It provides the $user object which you can use to implement custom logic as you wish.

Parameters

• $user – the user object of the user that needs to be redirected

Example code

add_action( 'wp_2fa_user_is_unlocked', 'my_custom_user_is_unlocked' );
function my_custom_user_is_unlocked( $user ) {
    $updated = update_user_meta( $user->ID, 'my-custom-key', ‘my-custom-value’ );
}

// Conditionally bypass the 2FA setup redirect for specific user roles.
// All other roles will still be forced to complete 2FA setup before 
// accessing the backend.
add_filter( 'wp_2fa_should_redirect_unconfigured', 'my_custom_2fa_redirect_logic' );
function my_custom_2fa_redirect_logic( $redirect ) {
    $user = wp_get_current_user();
    // Skip the 2FA setup redirect for subscribers — they can 
    // browse the backend freely even without configuring 2FA.
    if ( in_array( 'subscriber', (array) $user->roles ) ) {
        return false;
    }
    // All other roles: keep the default behavior (redirect to 2FA setup).
    return $redirect;
}