apply_filters( 'authenticate', null|WP_User|WP_Error $user, string $username, string $password )

Filters whether a set of user login credentials are valid.

Description Description

A WP_User object is returned if the credentials authenticate a user. WP_Error or null otherwise.

Parameters Parameters


(null|WP_User|WP_Error) WP_User if the user is authenticated. WP_Error or null otherwise.


(string) Username or email address.


(string) User password

Top ↑

Source Source

File: wp-includes/pluggable.php

View on Trac

Top ↑

Changelog Changelog

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

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Rahul Prajapati

    The basic usage is as follows…

    add_filter( 'authenticate', 'myplugin_auth_signon', 30, 3 );
    function myplugin_auth_signon( $user, $username, $password ) {
         return $user;

    This hook passes three parameters, $user, $username and $password. In order to generate an error on login, you will need to return a WP_Error object.

  2. Skip to note 2 content
    Contributed by pronl

    … or simply return null.

    WordPress will assign a standard WP_Error object:

    if ( $user == null ) {
    	// 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.' ) );

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