Authorization in REST API

In the REST API, there are public and private endpoints. Private ones require the user to be authenticated and have the appropriate permissions to perform actions. Authentication in the REST API is carried out during the request.

Authentication via cookies

Cookie-based authorization is the standard authentication method in WordPress. The user enters their login/password, based on which a cookie is created (and saved in the browser). Then, with this cookie, WP checks each time whether the user is authenticated.

To authorize via cookies in a REST request, it is necessary to pass a nonce-code. This is needed for security against Cross-Site Request Forgery (CSRF) attacks. This approach is only needed for processing requests that require special permissions, such as requests to delete/edit a post, category, etc.

If using the built-in Javascript API

You can forget about the nonce code, as the API does everything for you in this case. This is the recommended method for making requests to the REST API when creating plugins and themes, as it ensures that any request will be sent correctly. The base wp.api.models.Base can be extended.

If using custom AJAX requests

You need to pass the nonce code with each request manually. To create such a nonce code, use the key wp_rest - wp_create_nonce( 'wp_rest' ).

The nonce code can be passed through:

• _wpnonce — GET/POST request parameter.
• X-WP-Nonce — HEADER request header parameter.

See examples below.

The cookie-based authorization method will only work:

• for AJAX requests - when the REST API is used "inside" WordPress.
• when the current user is authenticated on the site.
• when the current user has sufficient permissions to perform the specified action (for example, deleting/editing a post).

Examples of setting the nonce code for custom AJAX requests:

#1 How to pass the nonce code in AJAX requests.

Suppose we generated a nonce code with the function wp_create_nonce( 'wp_rest' ) and it equals asdf654adsf, then:

Passing it in the _wpnonce parameter:

// GET request
let fetch = fetch( 'http://site/uri/?_wpnonce=asdf654adsf' );

// POST request
let fetch = fetch( 'http://site/uri/', {
	method: 'POST',
	body: new URLSearchParams( '_wpnonce=asdf654adsf&foo=bar' )
	// body: new URLSearchParams( [ ...new FormData(formElement).entries() ] )
} );

// POST request using jQuery
let request = jQuery.ajax( 'http://site/uri/', {
	method: "POST",
	data: {
		_wpnonce: "asdf654adsf",
		foo: "bar"
	}
} );

Passing it in the X-WP-Nonce header:

// fetch request
let fetch = fetch( 'http://site/uri/', {
	method: 'POST',
	headers: {
		'X-WP-Nonce': 'asdf654adsf'
	},
	body: new URLSearchParams( 'foo=bar' )
} );

// jQuery request
let request = jQuery.ajax( 'http://site/uri/', {
	method: "POST",
	headers: {
		'X-WP-Nonce': 'asdf654adsf'
	},
	data: { foo: "bar" }
} );

#1.2 How to create and pass the nonce code.

Let's create a nonce code and a link to the REST API, and add this data to HTML for later use:

wp_localize_script( 'my-js-file', 'REST_API_data', array(
	'root'  => esc_url_raw( rest_url() ),
	'nonce' => wp_create_nonce( 'wp_rest' )
) );

Now let's use the created data in the JS code.

Change the title of post 1. For this, use the route /wp/v2/posts/{id}:

jQuery.ajax( {
	url        : REST_API_data.root + 'wp/v2/posts/1',
	method     : 'POST',
	beforeSend : function ( xhr ) {
		xhr.setRequestHeader( 'X-WP-Nonce', REST_API_data.nonce );
	},
	data       : {
		'title' : 'New Title'
	}
} )
.done( function ( response ) {
	console.log( response );
} );

Other authentication methods

When another authorization method is needed, for example, to work with the site from an external application, use:

• Application passwords — a built-in capability.
• Plugin: OAuth 1.0a Server
• Plugin: JSON Web Tokens