check_ajax_referer( int|string $action = -1, false|string $query_arg = false, bool $stop = true ): int|false

Verifies the Ajax request to prevent processing requests external of the blog.

Parameters

$actionint|stringoptional
Action nonce.

Default:-1

$query_argfalse|stringoptional
Key to check for the nonce in $_REQUEST (since 2.5). If false, $_REQUEST values will be evaluated for '_ajax_nonce', and '_wpnonce' (in that order).

Default:false

$stopbooloptional
Whether to stop early when the nonce cannot be verified.

Default:true

Return

int|false 1 if the nonce is valid and generated between 0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
False if the nonce is invalid.

More Information

Nonces should never be relied on for authentication, authorization, or access control. Protect your functions using current_user_can() and always assume that nonces can be compromised.

This function can be replaced via plugins. If plugins do not redefine these functions, then this will be used instead.

If $query_arg is not specified (i.e. defaults to false), then the function will look for the nonce in '_ajax_nonce'. If that is not set, then it will assume that the nonce is in '_wpnonce', regardless of whether that query arg actually exists.

If $die is set to true, execution of the script will be stopped if the nonce cannot be verified, and the output will be '-1'.

Source

function check_ajax_referer( $action = -1, $query_arg = false, $stop = true ) {
	if ( -1 == $action ) {
		_doing_it_wrong( __FUNCTION__, __( 'You should specify an action to be verified by using the first parameter.' ), '4.7.0' );
	}

	$nonce = '';

	if ( $query_arg && isset( $_REQUEST[ $query_arg ] ) ) {
		$nonce = $_REQUEST[ $query_arg ];
	} elseif ( isset( $_REQUEST['_ajax_nonce'] ) ) {
		$nonce = $_REQUEST['_ajax_nonce'];
	} elseif ( isset( $_REQUEST['_wpnonce'] ) ) {
		$nonce = $_REQUEST['_wpnonce'];
	}

	$result = wp_verify_nonce( $nonce, $action );

	/**
	 * Fires once the Ajax request has been validated or not.
	 *
	 * @since 2.1.0
	 *
	 * @param string    $action The Ajax nonce action.
	 * @param false|int $result False if the nonce is invalid, 1 if the nonce is valid and generated between
	 *                          0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
	 */
	do_action( 'check_ajax_referer', $action, $result );

	if ( $stop && false === $result ) {
		if ( wp_doing_ajax() ) {
			wp_die( -1, 403 );
		} else {
			die( '-1' );
		}
	}

	return $result;
}

Hooks

do_action( ‘check_ajax_referer’, string $action, false|int $result )

Fires once the Ajax request has been validated or not.

Changelog

VersionDescription
2.0.3Introduced.

User Contributed Notes

  1. Skip to note 2 content

    Example
    In your main file, set the nonce like this:

    <?php
    //Set Your Nonce
    $ajax_nonce = wp_create_nonce( "wpdocs-special-string" );
    ?>
    
    <script type="text/javascript">
    jQuery(document).ready(function($){
    	var data = {
    		action: 'wpdocs_action',
    		security: '<?php echo $ajax_nonce; ?>',
    		wpdocs_string: 'Hello World!'
    	};
    	$.post(ajaxurl, data, function(response) {
    		alert("Response: " + response);
    	});
    });
    </script>

    In your AJAX file, check the referrer like this:

    /**
     * Check the referrer for the AJAX call.
     */
    function wpdocs_action_function() {
    	check_ajax_referer( 'wpdocs-special-string', 'security' );
    	echo sanitize_text_field( $_POST['wpdocs_string'] );
    	die;
    }
    add_action( 'wp_ajax_wpdocs_action', 'wpdocs_action_function' );

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