check_admin_referer( int|string $action = -1, string $query_arg = '_wpnonce' )

Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.


Description

This function ensures the user intends to perform a given action, which helps protect against clickjacking style attacks. It verifies intent, not authorization, therefore it does not verify the user’s capabilities. This should be performed with current_user_can() or similar.

If the nonce value is invalid, the function will exit with an "Are You Sure?" style message.


Parameters

$action

(Optional) The nonce action.

Default value: -1

$query_arg

(Optional) Key to check for nonce in $_REQUEST. Default '_wpnonce'.

Default value: '_wpnonce'


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.<br> False if the nonce is invalid.


Source

File: wp-includes/pluggable.php

function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
	if ( -1 === $action )
		_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), 'WP-3.2.0' );

	$adminurl = strtolower(admin_url());
	$referer = strtolower(wp_get_referer());
	$result = isset($_REQUEST[$query_arg]) ? wp_verify_nonce($_REQUEST[$query_arg], $action) : false;

	/**
	 * Fires once the admin request has been validated or not.
	 *
	 * @since WP-1.5.1
	 *
	 * @param string    $action The 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_admin_referer', $action, $result );

	if ( ! $result && ! ( -1 === $action && strpos( $referer, $adminurl ) === 0 ) ) {
		wp_nonce_ays( $action );
		die();
	}

	return $result;
}


Changelog

Changelog
Version Description
2.5.0 The $query_arg parameter was added.
1.2.0 Introduced.