wp_authenticate( string $username, string $password )

Authenticate a user, confirming the login credentials are valid.

Parameters Parameters


(string) (Required) User's username or email address.


(string) (Required) User's password.

Top ↑

Return Return

(WP_User|WP_Error) WP_User object if the credentials are valid, otherwise WP_Error.

Top ↑

More Information More Information

  • This is a plugabble function, which means that a plug-in can override this function.
  • Not to be confused with the wp_authenticate action hook.

Top ↑

Source Source

File: wp-includes/pluggable.php

	function wp_authenticate( $username, $password ) {
		$username = sanitize_user( $username );
		$password = trim( $password );

		 * Filters whether a set of user login credentials are valid.
		 * A WP_User object is returned if the credentials authenticate a user.
		 * WP_Error or null otherwise.
		 * @since 2.8.0
		 * @since 4.5.0 `$username` now accepts an email address.
		 * @param null|WP_User|WP_Error $user     WP_User if the user is authenticated.
		 *                                        WP_Error or null otherwise.
		 * @param string                $username Username or email address.
		 * @param string                $password User password
		$user = apply_filters( 'authenticate', null, $username, $password );

		if ( null == $user ) {
			// TODO: What should the error message be? (Or would these even happen?)
			// Only needed if all authentication handlers fail to return anything.
			$user = new WP_Error( 'authentication_failed', __( '<strong>Error</strong>: Invalid username, email address or incorrect password.' ) );

		$ignore_codes = array( 'empty_username', 'empty_password' );

		if ( is_wp_error( $user ) && ! in_array( $user->get_error_code(), $ignore_codes, true ) ) {
			$error = $user;

			 * Fires after a user login has failed.
			 * @since 2.5.0
			 * @since 4.5.0 The value of `$username` can now be an email address.
			 * @since 5.4.0 The `$error` parameter was added.
			 * @param string   $username Username or email address.
			 * @param WP_Error $error    A WP_Error object with the authentication failure details.
			do_action( 'wp_login_failed', $username, $error );

		return $user;

Top ↑

Changelog Changelog

Version Description
4.5.0 $username now accepts an email address.
2.5.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Md. Zubaer Ahammed

    Check whether credentials are valid or not for a defined user.

    $user = wp_authenticate($username, $password);
    if(!is_wp_error($user)) {
    	$first_name = $user->first_name;
    	echo "Login credentials are valid. First name is $first_name";
    } else {
    	echo "Invalid login credentials.";

You must log in before being able to contribute a note or feedback.