check_ajax_referer() – Function | Developer.WordPress.org

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

/**
 * Verifies the Ajax request to prevent processing requests external of the blog.
 *
 * @since 2.0.3
 *
 * @param int|string   $action    Action nonce.
 * @param false|string $query_arg Optional. 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.
 * @param bool         $stop      Optional. 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.
 */
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.

View all references View on Trac View on GitHub

Changelog

Version	Description
2.0.3	Introduced.

User Contributed Notes

Codex 10 years ago

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' );

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

In this article