Upgrading your Hootsuite App to platform.hootsuite.com

We're upgrading Hootsuite's API platform to make it more user-friendly and standards-compliant. If your app uses the Hootsuite API then you will need to update your app code before May 21st so that it can continue working. Here’s what you need to know:

What's new?

Major changes

These breaking changes affect all Hootsuite apps that use the API:

The hostname for API calls is now platform.hootsuite.com

In the past, requests to the Hootsuite API were made to the apis.hootsuite.com hostname. Going forward, API calls should be made to the platform.hootsuite.com domain name instead. Requests to apis.hootsuite.com will no longer work after May 21st.

The OAuth grant experience is simpler and supports SSO

The authorization code flow previously asked users to type in their Hootsuite password. Many users log in to Hootsuite using Okta or Twitter so this caused a small problem. Apps built on platform.hootsuite.com are fully compatible with SSO and users can install your app with a single click:

The OAuth 2.0 authorization and token endpoints are changing

Hootsuite users can authorize your app to access their account using OAuth 2.0. The authorization and access token endpoints are changing and you'll need to use these new ones after May 21st:

New OAuth scope

Hootsuite’s OAuth implementation has only one scope. That scope was oob. Going forward, your app should request the offline scope instead when implementing the OAuth 2.0 authorization code flow. We are also planning on introducing new scopes in the future.

Basic authorization must be used with the OAuth 2.0 token endpoint

Obtaining a Hootsuite access token requires sending your API client ID and client secret to the OAuth 2.0 token endpoint. In the past, Hootsuite supported passing your API client ID and secret as parameters in the body of the HTTP request.
Using the new platform, getting a token requires passing the client ID and client secret within a basic authorization header.

POST /oauth2/token HTTP/1.1
Host: platform.hootsuite.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic d2Vyd2Vyd2VycndlcmV3cndlcndlOndlcndlcmV3cndlcmV3cmVyd3J3ZXI=
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

const HOOTSUITE_CLIENT_ID = '';
const HOOTSUITE_CLIENT_SECRET = '';

$client = new Client([
    'base_uri' => 'https://platform.hootsuite.com'
]);
try {
    $response = $client->post('/auth/oauth/v2/token', [
        'form_params' => [
            'grant_type' => 'client_credentials'
        ],
        'headers' => [
            'Authorization' => 'Basic ' . base64_encode(HOOTSUITE_CLIENT_ID . ':' . HOOTSUITE_CLIENT_SECRET)
        ]
    ]);
} catch (GuzzleHttp\Exception\ClientException $e) {
    var_dump($e->getMessage());
}
$tokenData = $response->getBody();

Minor changes

These changes affect a subset of Hootsuite apps using the API:

Client credential grant type no longer needed. App Tokens can be granted in 1 step.

Previously, in order to retrieve a member or organization app token, you would first need to call the token endpoint using the client credentials grant type, and then use that access token to call either the member or organization app token endpoints to retrieve an access token to use with the REST API.

Now, you can retrieve the member or organization app token in one step, specifying the type of app token within the grant_type directly. As mentioned above, you'll need to pass the client_id and client_secret as HTTP basic auth headers. For more details, see our Authentication guide.

OAuth 2.0 state URL parameter must be 8 characters or longer

Requests to the /oauth2/auth endpoint can include a state URL parameter. If the state parameter is included then Hootsuite will append it to your app's redirect URI. Your app can help mitigate CSRF attacks by checking the state parameter you receive and making sure that it matches what you provided to Hootsuite.
The state parameter is optional but if your app includes it, then it must be 8 characters or longer.

Authorization error responses are changing

We are now supporting RFC6749 error responses for authorization errors. As a result, the older, non-standard authorization error response format is being replaced by the following RFC-compliant format:

{
  "error": "an_error_code",
  "error_description": "a description of the error with extra information"
}

Non-authorization error responses will continue to use the existing error format.

The access token expiry time is decreasing to one hour

Hootsuite access tokens that you receive from apis.hootsuite.com are valid for 30 days. Tokens that you obtain from platform.hootsuite.com will only be valid for one hour. If your app requires offline access to Hootsuite then you can use a refresh token to obtain a new token when the first one expires.

Resource owner password grant is no longer available

Hootsuite will no longer support the resource owner password grant. If you were using the resource owner password grant, try the authorization code workflow instead.

OAuth redirect URI must begin with https:// or http://localhost

Redirect URIs that begin with http:// are no longer compatible. If your app has an http:// redirection URI, let us know and we'll be glad to adjust the redirect URI whitelist for you.

Echo endpoint no longer supported

The /v1/echo endpoint has been removed. You can test out the API using other endpoints, like the /v1/me endpoint.

How do I upgrade my app?

The upgrade process will be different from app to app. This checklist can help you make a plan for upgrading your app before the deadline:

  • Change the hostname for your API requests to platform.hootsuite.com.
    After May 21st, all API calls will have to be made against this domain name and not apis.hootsuite.com.
  • Begin using the new OAuth 2.0 endpoints and the offline scope.
  • Use basic authorization when requesting a Hootsuite access token.
  • Check if your app is affected by any other breaking changes.
    The above steps will be enough for most apps. Take a look at the list of breaking changes and evaluate whether there are other changes that affect your app. For example, if your app uses the password grant type then you may need to switch your app to one of the other authorization workflows listed in the Authentication guide .
  • Test your app in a staging environment.
    Verify that your app is exchanging data correctly with Hootsuite and check to see that the authorization flow works. If necessary, make sure that your app is refreshing the access token after one hour.
  • Deploy your upgrades 🎉
    When you are sure that your app is compatible with platform.hootsuite.com then it's time to launch your changes to production. Make sure that you update your app ahead of May 15th to avoid any problems with how it works.

Have questions?

We're glad to help! Post any questions you have about these changes in the Hootsuite developer forum or email us directly if you're encountering specific errors!

Upgrading your Hootsuite App to platform.hootsuite.com


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.