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

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. Only possible when $stop is false, as the function otherwise exits rather than returning false.

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;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘check_ajax_referer’, string $action, false|int $result ): Fires once the Ajax request has been validated or not.

Uses	Description
wp_doing_ajax()`wp-includes/load.php`	Determines whether the current request is a WordPress Ajax request.
wp_verify_nonce()`wp-includes/pluggable.php`	Verifies that a correct security nonce was used with time limit.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
_doing_it_wrong()`wp-includes/functions.php`	Marks something as being incorrectly called.
wp_die()`wp-includes/functions.php`	Kills WordPress execution and displays HTML page with an error message.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 4 more Show less

Used by	Description
WP_Plugin_Dependencies::check_plugin_dependencies_during_ajax()`wp-includes/class-wp-plugin-dependencies.php`	Checks plugin dependencies after a plugin is installed via AJAX.
wp_ajax_activate_plugin()`wp-admin/includes/ajax-actions.php`	Handles activating a plugin via AJAX.
wp_ajax_send_password_reset()`wp-admin/includes/ajax-actions.php`	Handles sending a password reset link via AJAX.
wp_ajax_toggle_auto_updates()`wp-admin/includes/ajax-actions.php`	Handles enabling or disable plugin and theme auto-updates via AJAX.
wp_ajax_media_create_image_subsizes()`wp-admin/includes/ajax-actions.php`	Handles creating missing image sub-sizes for just uploaded images via AJAX.
wp_ajax_health_check_get_sizes()`wp-admin/includes/ajax-actions.php`	Handles site health check to get directories and database sizes via AJAX.
wp_ajax_health_check_dotorg_communication()`wp-admin/includes/ajax-actions.php`	Handles site health checks on server communication via AJAX.
wp_ajax_health_check_background_updates()`wp-admin/includes/ajax-actions.php`	Handles site health checks on background updates via AJAX.
wp_ajax_health_check_loopback_requests()`wp-admin/includes/ajax-actions.php`	Handles site health checks on loopback requests via AJAX.
wp_ajax_health_check_site_status_result()`wp-admin/includes/ajax-actions.php`	Handles site health check to update the result status via AJAX.
wp_ajax_wp_privacy_export_personal_data()`wp-admin/includes/ajax-actions.php`	Handles exporting a user’s personal data via AJAX.
wp_ajax_wp_privacy_erase_personal_data()`wp-admin/includes/ajax-actions.php`	Handles erasing personal data via AJAX.
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Customize_Manager::handle_override_changeset_lock_request()`wp-includes/class-wp-customize-manager.php`	Removes changeset lock when take over request is sent via Ajax.
WP_Customize_Manager::handle_dismiss_autosave_or_lock_request()`wp-includes/class-wp-customize-manager.php`	Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
WP_Customize_Manager::handle_changeset_trash_request()`wp-includes/class-wp-customize-manager.php`	Handles request to trash a changeset.
wp_ajax_get_community_events()`wp-admin/includes/ajax-actions.php`	Handles Ajax requests for community events
WP_Customize_Nav_Menus::ajax_insert_auto_draft_post()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for adding a new auto-draft post.
wp_ajax_search_install_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins to install via AJAX.
wp_ajax_delete_plugin()`wp-admin/includes/ajax-actions.php`	Handles deleting a plugin via AJAX.
wp_ajax_search_plugins()`wp-admin/includes/ajax-actions.php`	Handles searching plugins via AJAX.
wp_ajax_install_theme()`wp-admin/includes/ajax-actions.php`	Handles installing a theme via AJAX.
wp_ajax_update_theme()`wp-admin/includes/ajax-actions.php`	Handles updating a theme via AJAX.
wp_ajax_delete_theme()`wp-admin/includes/ajax-actions.php`	Handles deleting a theme via AJAX.
wp_ajax_install_plugin()`wp-admin/includes/ajax-actions.php`	Handles installing a plugin via AJAX.
wp_ajax_get_post_thumbnail_html()`wp-admin/includes/ajax-actions.php`	Handles retrieving HTML for the featured image via AJAX.
wp_ajax_save_wporg_username()`wp-admin/includes/ajax-actions.php`	Handles saving the user’s WordPress.org username via AJAX.
wp_ajax_delete_inactive_widgets()`wp-admin/includes/ajax-actions.php`	Handles removing inactive widgets via AJAX.
WP_Customize_Nav_Menus::ajax_load_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for loading available menu items.
WP_Customize_Nav_Menus::ajax_search_available_items()`wp-includes/class-wp-customize-nav-menus.php`	Ajax handler for searching available menu items.
wp_ajax_crop_image()`wp-admin/includes/ajax-actions.php`	Handles cropping an image via AJAX.
wp_ajax_update_plugin()`wp-admin/includes/ajax-actions.php`	Handles updating a plugin via AJAX.
Custom_Background::ajax_background_add()`wp-admin/includes/class-custom-background.php`	Handles Ajax request for adding custom background context to an attachment.
wp_ajax_set_attachment_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image for an attachment via AJAX.
wp_ajax_save_attachment_order()`wp-admin/includes/ajax-actions.php`	Handles saving the attachment order via AJAX.
wp_ajax_send_attachment_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending an attachment to the editor via AJAX.
wp_ajax_send_link_to_editor()`wp-admin/includes/ajax-actions.php`	Handles sending a link to the editor via AJAX.
wp_ajax_save_user_color_scheme()`wp-admin/includes/ajax-actions.php`	Handles auto-saving the selected color scheme for a user’s own profile via AJAX.
wp_ajax_save_widget()`wp-admin/includes/ajax-actions.php`	Handles saving a widget via AJAX.
wp_ajax_upload_attachment()`wp-admin/includes/ajax-actions.php`	Handles uploading attachments via AJAX.
wp_ajax_image_editor()`wp-admin/includes/ajax-actions.php`	Handles image editing via AJAX.
wp_ajax_set_post_thumbnail()`wp-admin/includes/ajax-actions.php`	Handles setting the featured image via AJAX.
wp_ajax_wp_fullscreen_save_post()`wp-admin/includes/ajax-actions.php`	Handles saving posts from the fullscreen editor via AJAX.
wp_ajax_wp_remove_post_lock()`wp-admin/includes/ajax-actions.php`	Handles removing a post lock via AJAX.
wp_ajax_save_attachment()`wp-admin/includes/ajax-actions.php`	Handles updating attachment attributes via AJAX.
wp_ajax_save_attachment_compat()`wp-admin/includes/ajax-actions.php`	Handles saving backward compatible attachment attributes via AJAX.
wp_ajax_add_menu_item()`wp-admin/includes/ajax-actions.php`	Handles adding a menu item via AJAX.
wp_ajax_add_meta()`wp-admin/includes/ajax-actions.php`	Handles adding meta via AJAX.
wp_ajax_add_user()`wp-admin/includes/ajax-actions.php`	Handles adding a user via AJAX.
wp_ajax_closed_postboxes()`wp-admin/includes/ajax-actions.php`	Handles closed post boxes via AJAX.
wp_ajax_hidden_columns()`wp-admin/includes/ajax-actions.php`	Handles hidden columns via AJAX.
wp_ajax_update_welcome_panel()`wp-admin/includes/ajax-actions.php`	Handles updating whether to display the welcome panel via AJAX.
wp_ajax_wp_link_ajax()`wp-admin/includes/ajax-actions.php`	Handles internal linking via AJAX.
wp_ajax_menu_locations_save()`wp-admin/includes/ajax-actions.php`	Handles saving menu locations via AJAX.
wp_ajax_meta_box_order()`wp-admin/includes/ajax-actions.php`	Handles saving the meta box order via AJAX.
wp_ajax_get_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a permalink via AJAX.
wp_ajax_sample_permalink()`wp-admin/includes/ajax-actions.php`	Handles retrieving a sample permalink via AJAX.
wp_ajax_inline_save()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving a post from a list table via AJAX.
wp_ajax_inline_save_tax()`wp-admin/includes/ajax-actions.php`	Handles Quick Edit saving for a term via AJAX.
wp_ajax_find_posts()`wp-admin/includes/ajax-actions.php`	Handles querying posts for the Find Posts modal via AJAX.
wp_ajax_widgets_order()`wp-admin/includes/ajax-actions.php`	Handles saving the widgets order via AJAX.
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
wp_ajax_delete_comment()`wp-admin/includes/ajax-actions.php`	Handles deleting a comment via AJAX.
wp_ajax_delete_tag()`wp-admin/includes/ajax-actions.php`	Handles deleting a tag via AJAX.
wp_ajax_delete_link()`wp-admin/includes/ajax-actions.php`	Handles deleting a link via AJAX.
wp_ajax_delete_meta()`wp-admin/includes/ajax-actions.php`	Handles deleting meta via AJAX.
wp_ajax_delete_post()`wp-admin/includes/ajax-actions.php`	Handles deleting a post via AJAX.
wp_ajax_trash_post()`wp-admin/includes/ajax-actions.php`	Handles sending a post to the Trash via AJAX.
wp_ajax_delete_page()`wp-admin/includes/ajax-actions.php`	Handles deleting a page via AJAX.
wp_ajax_dim_comment()`wp-admin/includes/ajax-actions.php`	Handles dimming a comment via AJAX.
wp_ajax_add_link_category()`wp-admin/includes/ajax-actions.php`	Handles adding a link category via AJAX.
wp_ajax_add_tag()`wp-admin/includes/ajax-actions.php`	Handles adding a tag via AJAX.
wp_ajax_get_comments()`wp-admin/includes/ajax-actions.php`	Handles getting comments via AJAX.
wp_ajax_replyto_comment()`wp-admin/includes/ajax-actions.php`	Handles replying to a comment via AJAX.
wp_ajax_edit_comment()`wp-admin/includes/ajax-actions.php`	Handles editing a comment via AJAX.
wp_ajax_fetch_list()`wp-admin/includes/ajax-actions.php`	Handles fetching a list table via AJAX.
wp_ajax_wp_compression_test()`wp-admin/includes/ajax-actions.php`	Handles compression testing via AJAX.
wp_ajax_imgedit_preview()`wp-admin/includes/ajax-actions.php`	Handles image editor previews via AJAX.
Custom_Image_Header::ajax_header_crop()`wp-admin/includes/class-custom-image-header.php`	Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
Custom_Image_Header::ajax_header_add()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, updates its “last used” timestamp to now.
Custom_Image_Header::ajax_header_remove()`wp-admin/includes/class-custom-image-header.php`	Given an attachment ID for a header image, unsets it as a user-uploaded header image for the active theme.
Custom_Background::wp_set_background_image()`wp-admin/includes/class-custom-background.php`
WP_Customize_Manager::save()`wp-includes/class-wp-customize-manager.php`	Handles customize_save WP Ajax request to save/update a changeset.
WP_Customize_Manager::setup_theme()`wp-includes/class-wp-customize-manager.php`	Starts preview and customize theme.
WP_Customize_Widgets::wp_ajax_update_widget()`wp-includes/class-wp-customize-widgets.php`	Updates widget settings asynchronously.

Show 80 more Show less

Changelog

Version	Description
2.0.3	Introduced.

User Contributed Notes

Codex 11 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