Engagement API

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

HootSuite API OAuth 2 Flowchart

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

Parameter Accepted Values
response_typeREQUIRED"code"
client_idREQUIREDAs provided by HootSuite
redirect_uriOPTIONALAbsolute URL
stateRECOMMENDEDUnique hash (e.g. session ID) provided by client. Will be passed back in grant response.

Example:

(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:

Parameter Value
codeAuthorization Grant code. Unique hash, valid for 10 minutes
stateAs provided by client in step (A)

(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:

Parameter Value
error
access_deniedThe resource owner or authorization server denied the request.
server_errorThe authorization server encountered an unexpected condition which prevented it from fulfilling the request.
error_descriptionHuman-readable description of error (optional)
stateAs provided by client in step (A)

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.

Parameter Accepted Values
grant_typeREQUIRED"authorization_code"
codeREQUIREDAuthorization Grant code issued in step A
redirect_uriOPTIONAL/REQUIREDREQUIRED, if the redirect_uri parameter was included in the authorization request (A), and their values MUST be identical.

Sample Code:

cURL

PHP

Ruby

(D) Access Token (Response)

Parameter Value
access_tokenUnique hash
token_type"bearer"
expires_inToken lifetime in seconds. Currently defaults to 1 year (3600*24*365 sec).

Response format: JSON. For example:

(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.

Parameter Value
error
Code Description HTTP status code
invalid_request The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. 400 (Bad Request)
invalid_client Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method). Response may include WWW-Authenticate header. 401 (Unauthorized)
invalid_grant The provided Authorization Grant (e.g. authorization code, resource owner credentials) is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. 400 (Bad Request)
error_descriptionHuman-readable description of error (optional)

Response format: JSON. For example:

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:

where vF9dft4qmT is the actual Access Token.

This is currently the only supported authentication method.

Sample cURL command:

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.

Parameter Value
error
Code Description HTTP status code
invalid_request The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed. 400 (Bad Request)
invalid_token The access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the protected resource request. 401 (Unauthorized)
error_descriptionHuman-readable description of error

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

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