Authentication Edit Page

This documentation has moved to The WordPress REST API Handbook. The below may be out of date.

There are several options for authenticating with the API. The basic choice boils down to:

Cookie authentication is the basic authentication method included with WordPress. When you log in to your dashboard, this sets up the cookies correctly for you, so plugin and theme developers need only to have a logged-in user.

However, the REST API includes a technique called nonces to avoid CSRF issues. This prevents other sites from forcing you to perform actions without explicitly intending to do so. This requires slightly special handling for the API.

For developers using the built-in Javascript API, this is handled automatically for you. This is the recommended way to use the API for plugins and themes. Custom data models can extend wp.api.models.Base to ensure this is sent correctly for any custom requests.

For developers making manual Ajax requests, the nonce will need to be passed with each request. The API uses nonces with the action set to wp_rest. These can then be passed to the API via the _wpnonce data parameter (either POST data or in the query for GET requests), or via the X-WP-Nonce header.

Note: Until recently, most software had spotty support for DELETE requests. For instance, PHP doesn’t transform the request body of a DELETE request into a super global. As such, supplying the nonce as a header is the most reliable approach.

It is important to keep in mind that this authentication method relies on WordPress cookies. As a result this method is only applicable when the REST API is used inside of WordPress and the current user is logged in. In addition, the current user must have the appropriate capability to perform the action being performed.

As an example, this is how the built-in Javascript client creates the nonce:

wp_localize_script( 'wp-api', 'wpApiSettings', array( 'root' => esc_url_raw( rest_url() ), 'nonce' => wp_create_nonce( 'wp_rest' ) ) );

This is then used in the base model:

options.beforeSend = function(xhr) {
	xhr.setRequestHeader('X-WP-Nonce', wpApiSettings.nonce);

	if (beforeSend) {
		return beforeSend.apply(this, arguments);

Here is an example of editing the title of a post, using jQuery AJAX:

$.ajax( {
    url: wpApiSettings.root + 'wp/v2/posts/1',
    method: 'POST',
    beforeSend: function ( xhr ) {
        xhr.setRequestHeader( 'X-WP-Nonce', wpApiSettings.nonce );
        'title' : 'Hello Moon'
} ).done( function ( response ) {
    console.log( response );
} );

OAuth Authentication

OAuth authentication is the main authentication handler used for external clients. With OAuth authentication, users still only ever log in via the normal WP login form, and then authorize clients to act on their behalf. Clients are then issued with OAuth tokens that enable them to access the API. This access can be revoked by users at any point.

OAuth authentication uses the OAuth 1.0a specification (published as RFC5849) and requires installing the OAuth plugin on the site.

Once you have WP API and the OAuth server plugins activated on your server, you’ll need to create a “client”. This is an identifier for the application, and includes a “key” and “secret”, both needed to link to your site.

The OAuth server plugin now has a full admin UI, including client application management and the ability to revoke tokens. To generate a new client application, you should see an “Applications” item appear under the users menu: this is where you manage OAuth clients.

You can also use WPCLI to generate client credentials on your server. To create the client, run the following on your server:

$ wp oauth1 add

ID: 4
Key: sDc51JgH2mFu
Secret: LnUdIsyhPFnURkatekRIAUfYV7nmP4iF3AVxkS5PRHPXxgOW

This key and secret is your client key and secret, and needs to be used throughout the authorization process.

For examples on how to use OAuth Authentication, as a starting point, we suggest you checkout the Demo PHP API Client, the CLI client or the API console.

Application Passwords or Basic Authentication

Basic authentication is an optional authentication handler for external clients. Due to the complexity of OAuth authentication, basic authentication can be useful during development. However, Basic authentication requires passing your username and password on every request, as well as giving your credentials to clients, so it is heavily discouraged for production use.

Application passwords are used similarly, however instead of providing your normal account password, unique and easily revokable passwords are generated from your edit profile screen in the WordPress admin. These application passwords are valid exclusively for the REST API and the legacy XML-RPC API and may not be used to log in to WordPress.

Both basic authentication and application passwords use HTTP Basic Authentication (published as RFC2617) and requires installing either the Basic Auth plugin or Application Passwords plugin respectively.

To use Basic authentication, simply pass the username and password with each request through the Authorization header. This value should be encoded (using base64 encoding) as per the HTTP Basic specification.

This is an example of how to update a post, using these authentications, via the WordPress HTTP API:

$headers = array (
	'Authorization' => 'Basic ' . base64_encode( 'admin' . ':' . '12345' ),
$url = rest_url( 'wp/v2/posts/1' );

$data = array(
	'title' => 'Hello Gaia' 

$response = wp_remote_post( $url, array (
    'method'  => 'POST',
    'headers' => $headers,
    'body'    =>  $data
) );