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.

Contents

Parameters

$action int|string Optional
Action nonce.

Default: -1

$query_arg false|string 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

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

Default: true

Top ↑

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.

Top ↑

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'.

Top ↑

Source

File: wp-includes/pluggable.php. View all references 

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 on Trac View on GitHub

Top ↑

Hooks

Top ↑

Top ↑

Uses

Uses
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 uses Hide more uses

Top ↑

Used By

Used By
Used By Description
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 78 more used by Hide more used by

Top ↑

Changelog

Changelog
Version Description
2.0.3 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 6You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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.