Using OAuth 2 with the HootSuite API

This document describes HootSuite's implementation of the OAuth 2 standard and how you can use it to make authenticated requests against the HootSuite Engagement API. The implementation is based on the OAuth 2.0 Draft 23 and the specific implementation details are outlined within the scope of this document.

Implementation Summary

This implementation is designed to use the Authorization Grant type Authorization Code: The HootSuite user first grants authorization to the Client (i.e. your app), which then presents the authorization code to a token endpoint in order to receive an access token.
Refresh tokens are currently not supported.

Client Authentication

Every Client (app) needs to be registered with HootSuite before being issued a Client ID and secret key (apply here). The Client ID is required when asking for the user's authorization; When requesting an access token, the Client has to authenticate using its ID and secret key via basic HTTP authentication.

Protocol Flow

Obtaining authorization from HootSuite user

(A) The Client redirects the HootSuite user's user-agent to HootSuite's Authorization Endpoint, which displays an HTML page containing a form that asks the HootSuite user to allow the Client to access their account data (Authorization Grant).

(B) Once the HootSuite user approves or denies the Client, the Authorization Endpoint redirects the user-agent back to the Client's redirect_uri along with the parameters outlined below (which include an Authorization Grant code if the user approved the Client).

(A) Authorization Request

GET http://hootsuite.com/oauth2/authorize

Example:

http://hootsuite.com/oauth2/authorize?response_type=code&client_id=abc123

(B) Authorization Grant (Response)

GET redirect_uri ("302 Found" redirect)

The HootSuite user has authorized the Client, and the user-agent is redirected to the redirect_uri which contains these parameters:

(B) Authorization Error (Response)

GET redirect_uri ("302 Found" redirect)

The HootSuite user has denied the Client or an unexpected error occured. The user-agent is redirected to the redirect_uri which contains these parameters:

Obtaining an Access Token

Once the Client has obtained authorization from the HootSuite user, it requests an Access Token at the Token Endpoint. It needs to authenticate itself using HTTP Basic Auth and present the Authorization Grant code.

This endpoint requires HTTPS.

(C) Access Token Request

POST https://hootsuite.com/oauth2/token

Requires client authentication (ID and secret key) via HTTP Basic Auth.

Sample Code:

cURL

curl -X POST -u 'CLIENT_ID:SECRET_KEY' -d 'grant_type=authorization_code&code=AUTH_CODE' https://hootsuite.com/oauth2/token

PHP

				
$curl = curl_init();
$data = array(
	'grant_type' => "authorization_code",
	'code'       => "AUTH_CODE"
);
curl_setopt( $curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt( $curl, CURLOPT_USERPWD, "CLIENT_ID:SECRET_KEY");
curl_setopt( $curl, CURLOPT_POST, true);
curl_setopt( $curl, CURLOPT_POSTFIELDS, $data);
curl_setopt( $curl, CURLOPT_URL, 'https://hootsuite.com/oauth2/token');

$result = json_decode(curl_exec($curl), true);

$check = curl_getinfo($curl);
if ($check['http_code'] == 200) 
{
	// $result like:
	// array(
	//     'access_token' => 'vF9dft4qmT',
	//     'token_type'   => 'bearer',
	//     'expires'      => 31536000
	// );
	
} else {

	// $result like:
	// array(
	//     'error'             => 'invalid_request',
	//     'error_description' => 'This endpoint requires HTTPS',
	// );
}

Ruby

# require 'rubygems'
require 'net/https'
require 'json'
 
uri = URI.parse("https://hootsuite.com/oauth2/token")
 
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
 
req = {"grant_type" => "authorization_code", "code" => "AUTH_CODE"}
 
request = Net::HTTP::Post.new(uri.request_uri)
request.basic_auth "CLIENT_ID", "SECRET_KEY"
request.body = JSON.generate(req)
 
response = http.request(request)
puts response.body

(D) Access Token (Response)

Response format: JSON. For example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "vF9dft4qmT",
  "token_type": "bearer",
  "expires_in": 31536000
}

(D) Access Token (Error Response)

If the request is malformed, contains invalid values, or if the provided Authorization Grant can not be validated (e.g. invalid code, it expired), the server responds with the appropriate HTTP status code (400 or 401) as well as an error code as outlined below, and may contain a human-readable error message.

Response format: JSON. For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "This endpoint requires HTTPS"
}

Accessing protected resources

The Access Token can now be used to run requests against the API on behalf of the HootSuite user.

All such requests require HTTPS.

(E) Access Token

In accordance with the Bearer Token specifications (http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-08#section-2), the Access Token is included with the request in the "Authorization" header as follows:

Authorization: Bearer vF9dft4qmT

where vF9dft4qmT is the actual Access Token.

This is currently the only supported authentication method.

Sample cURL command:

curl -i -G -H "Authorization: Bearer vF9dft4qmT" https://api.hootsuite.com/api/2/networks

Note: For more code samples refer to the API documentation.

(F) Protected Resource (Error Response)

If the request is malformed, contains invalid values, or if the provided Access Token can not be validated (e.g. invalid code, it expired), the server responds with the appropriate HTTP status code (400 or 401) as well as a "WWW-Authenticate" header, which may contain an error code and message as outlined below.

For example, in response to a protected resource request without authentication:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="HootSuite Engagement API"

And in response to a protected resource request with an authentication attempt using an expired access token:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="HootSuite Engagement API",
                  error="invalid_token",
                  error_description="The access token expired"