Update: For more information, you can download our free ebook, The Ultimate Guide to the WordPress REST API.
The new JSON REST API is one of the more exciting developments in the WordPress world. One of the parts of working with the API that has generated the most confusion is authentication. In this article I will give you a brief introduction to how authentication works with the REST API and the authentication system provided by the REST API team. I will also introduce some additional tools that will make using them even easier.
Understanding authentication with the REST API
How authentication works
How authentication methods work is beyond the scope of this article, I do however want to briefly cover how authentication works with the REST API.
The REST API does not reinvent how user authentication and roles work in WordPress. Each of the various authentication methods work to set the current user, in general by passing a username and password to wp_authenticate() in a function hooked to determine_current_user.
Once the current user is set, the REST API does the same type of permission checks that any other plugin, theme, or part of WordPress core does. This is all to say that what is new and confusing about the REST API is not how permissions are handled but how the current user is set.
Do you need authentication?
The REST API is not reinventing how permissions work in WordPress, it is designed to show any data that a non-logged in user could see without authentication. In many cases, there is no need to authenticate at all.
In some cases — when you need to make a query that involves one or two parameters that require authentication — it might not make sense to authenticate. Instead, it is easier and more secure to just make those parameters publicly queryable via one of the many filters that the REST API provides. In that same vein, there may be times where you may want to use various filters to enable access to the specific part of the REST API that a plugin or theme you are developing needs.
The REST API project provides a basic authentication system, which is very easy to use but should not be used in production, because it transmits usernames and passwords as plain strings.
By “in production” I mean any site on the internet. This simple system is great for testing a site running in your local development environment on your computer. Beyond that, it’s of limited use.
Key pair authentication
Another simple, yet more secure system is the key authorization system, which is primarily written by Paul Hughes. This system uses public key cryptography — a pattern in which each user has a public and private key. The public key is sent with the request. Once the request is made, both the transmitted public key and the user’s private key, which is stored in the site’s database, are used to authenticate the user.
This type of system is considered to be fairly secure. However, it has several weaknesses. One of which is that the public key may be intercepted while in transit by a hacker, government agency, or some other evildoer. This risk is mitigated by using HTTPS. An additional concern is that, like all cryptography, the keys may be brute-forced.
This solution is easy to use, and is a great choice for many situations. You will want to make sure that it is only used over HTTPS for the reasons I discussed above. You will probably want to create your own admin UI for creating the keys, since the plugin does not provide that for you.
The REST API team provides an oAuth1 server for WordPress, designed to work well with the the REST API, though it can be used for other applications where remote authentication to a WordPress site is required.
oAuth1 is the most complicated and the most secure way to make authenticated requests to the REST API. But, since oAuth1 is an established standard, once you are familiar with the standard, which you may already be, using oAuth1 with the WordPress REST API, or in other situations will be easy for you.
There is also a great tool, provided by WebDev Studios for making authenticated requests to the API using oAuth1 authentication. The oAuth1 server also does not have a UI for creating “consumer” credentials for users to use via oAuth1. There is a fork that has a UI though.
More to come
In this article I’ve given you a brief introduction to the main authentication methods for the REST API. The REST API is still very new, and new tools for it are popping up every day. As time goes on there will be more ways to authenticate and to use the existing tools.
I encourage you to take a look at the existing tools and use them as inspiration for creating your own.
If you’ve created your own tool, or found one that I didn’t cover, be sure to share it in the comments below!