WP 2FA REST API Documentation

This documentation covers WP 2FA’s core REST API endpoint for validating a user’s second-factor authentication token, including TOTP, email codes, backup codes, SMS codes, and other supported token-based providers.

Note: If you are integrating passwordless authentication or WebAuthn credentials, see the separate Passkey (WebAuthn) API documentation.

Endpoint

Namespace: wp-2fa-methods/v1

POST /wp-json/wp-2fa-methods/v1/login/<user_id>/<token>/<provider>/<remember_device>

Only POST is accepted. Other HTTP methods are rejected with a 405 response.

Parameters

Note: The route schema marks token as optional, but the URL pattern requires it – a request will fail to match without a token segment.

Supported providers

The endpoint validates tokens through any provider registered via the wp_2fa_validate_login_api filter. The built-in providers are:

The Out-of-Band email link method (oob) is also available in Premium, but it completes authentication through an email link rather than a token submission, so it does not participate in this REST endpoint.

Response

A successful call returns:

{
  "status": true,
  "message": "Successfully signed in with WP 2FA.",
  "redirect_to": "https://example.com/wp-admin/"
}

On failure, status is false and message describes the reason (invalid code, too many attempts, no method enabled, and so on). Hard errors – missing user, wrong HTTP method, or a missing/expired login nonce – return a WP_Error with HTTP status 400 or 405.

Login flow requirements

Before calling the endpoint, the user must have a valid login nonce stored in user meta. WP 2FA creates this automatically during the standard login flow (after password verification, before second-factor verification). The nonce is consumed on a successful response and cannot be reused.

The endpoint enforces the same login-attempt limit as the standard 2FA screen. After too many failed attempts, the response returns status: false with a “Too many attempts” message and a redirect to the login URL.

Minimal example

// remember_device is optional and can be omitted
const res = await wp.apiFetch( {
  path: '/wp-2fa-methods/v1/login/' + userId + '/' + token + '/' + provider,
  method: 'POST',
} );
if ( res.status === true ) {
  window.location.href = res.redirect_to;
}

Helper functions

User_Helper exposes the methods most integrations need. Each accepts the user as an int (user ID), a WP_User object, a string (the user’s user_login), or null (the current user).

Get the user’s enabled 2FA method

\WP2FA\Admin\Helpers\User_Helper::get_enabled_method_for_user( $user );

Returns the slug of the user’s currently enabled primary method, or an empty value if none is configured.

Get the user’s enabled backup methods

\WP2FA\Admin\Helpers\User_Helper::get_enabled_backup_methods_for_user( $user );

Returns an array of backup method slugs available to the user. In Premium, this typically includes backup_codes and, if enabled, backup_email.

Sending email backup codes (Premium)

The Email Backup extension can deliver a backup authentication code by email. This is the backup_email provider, used as a fallback when the user cannot complete their primary method.

\WP2FA\Extensions\EmailBackup\Email_Backup::send_user_authentication_email( $user );

The $user argument accepts the same formats as User_Helper. Email backup codes must be enabled in the plugin settings before this call will deliver anything.

Hooks for custom integrations

The endpoint validates tokens through a filter, which is how the built-in providers register themselves. Custom providers can hook into the same filter:

add_filter( 'wp_2fa_validate_login_api', function( $valid, $user_id, $token, $provider ) {
  // Run your own check, then return:
  // $valid['valid'] = true;  // on success
  // $valid['valid'] = false; // on failure
  return $valid;
}, 10, 4 );

Other useful hooks fired by the endpoint:

• wp_2fa_user_authenticated (action) – fires after a successful sign-in. Receives the WP_User.
• wp_2fa_remember_device (action) – fires when remember_device is truthy. Receives the WP_User and the raw value. The Premium Trusted Devices extension is the listener that persists the record; without Premium, the action fires, but nothing acts on it.
• wp_2fa_post_login_user_redirect (filter) – adjust the redirect URL returned in the response.
• wp_2fa_api_endpoints (filter) – register additional REST routes under the WP 2FA namespace.

Disabling the endpoint

The REST endpoint is registered by default. To turn it off, go to WP 2FA > Settings > General Settings and tick Disable the REST API endpoints for 2FA. When enabled, the endpoint is not registered with WordPress at all.