OAuth2 is a protocol that allows applications to interact with blogs on WordPress.com and self-hosted WordPress sites running Jetpack.

The primary goal of OAuth is to allow developers to interact with WordPress.com and Jetpack sites without requiring them to store sensitive credentials. Our implementation also allows users to manage their own connections.

If you are new to the world of OAuth, you can read more at http://oauth.net.

If you are already familiar with OAuth, then all you really need to know about are the two authentication endpoints. The authorization endpoint and the token request endpoint.

These endpoints are

https://public-api.wordpress.com/oauth2/authorize

https://public-api.wordpress.com/oauth2/token

The same endpoints are used for WordPress.com blogs and Jetpack sites.

Before you begin to develop an application, you will need a client id and a client secret key. The client id and client secret key will be used to authenticate your application and verify that the API calls being are valid. You can sign up for an id and secret at our applications manager.

Receiving an Access Token

To act on a user’s behalf and make calls from our API you will need an access token. To get an access token you need to go through the access token flow and prompt the user to authorize your application to act on his or her behalf.

Access tokens are currently per blog per user for most of our endpoints. This means that you will need a separate access token for each blog that a user owns and that you want access to. There are certain endpoints like likes and follows where you can use a users token on any blog to act on their behalf.

To begin, you will need to send the user to the authorization endpoint.

https://public-api.wordpress.com/oauth2/authorize?client_id=your_client_id&redirect_uri=your_url&response_type=code

client_id should be set to your application’s client id. response_type should always be set to “code”. redirect_uri should be set to the URL that the user will be redirected back to after the request is authorized. The redirect_uri should be set in the applications manager.

The redirect to your application will include a code which you will need in the next step. If the user has denied access to your app, the redirect will include ?error=access_denied

Optionally you may also pass along a blog parameter (&blog=) with the URL to a WordPress.com blog or Jetpack site. If you do not pass along a URL, or if the user does not have administrative access to manage the blog you passed along, then the user will be prompted to select the blog they are granting you access to.

Once the user has authorized the request, he or she will be redirected to the redirect_url. The request will look like the following:

http://developer.wordpress.com/?code=cw9hk1xG9k

This is a time-limited code that your application can exchange for a full authorization token. To do this you will need to pass the code to the token endpoint by making a POST request to the token endpoint: https://public-api.wordpress.com/oauth2/token.

$curl = curl_init( "https://public-api.wordpress.com/oauth2/token" );
curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
	'client_id' => your_client_id,
	'redirect_uri' => your_redirect_url,
	'client_secret' => your_client_secret_key,
	'code' => $_GET['code'], // The code from the previous request
	'grant_type' => 'authorization_code'
) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$secret = json_decode($auth);
$access_key = $secret->access_token;

You are required to pass client_id, client_secret, and redirect_uri for web applications. These parameters have to match the details for your application, and the redirect_uri must match the redirect_uri used during the Authorize step (above).¬†grant_type has to be set to “authorization_code”. code must match the code you received in the redirect.

If everything works correctly and the user grants authorization, you will get back a JSON-encoded string containing the token and some basic information about the blog:

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog id",
    "blog_url": "blog url",
    "token_type": "bearer"
}

You now have an access token which should be stored securely with the blog id and blog url. This access token allows our application to act on the behalf of the user on this specific blog.

Making an API Call

Our API is JSON based. You can view all of the available endpoints at our API documentation. You can also make API calls with our legacy XML-RPC API.

In order to make an authenticated call to your APIS, you need to include your access token with the call. OAuth2 uses a BEARER token that is passed along in an Authorization header.

<?php
$access_key = "YOUR_API_TOKEN";
$curl = curl_init( "https://public-api.wordpress.com/rest/v1/me/" );
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_key ) );
curl_exec( $curl );
?>

The above example would return information about the authenticated user. You can make similar calls to the other available endpoints.