Set up your App

This guide describes how to set up and configure a Hootsuite App. Apps that are within the Hootsuite Ecosystem are Hootsuite internal apps that run within Hootsuite.com only. External apps can reside anywhere online and communicate with Hootsuite remotely. It can be explained as follows:

REST API - This is a REST API framework that allows you to build Hootsuite integrated apps external of the Hootsuite Ecosystem. Access token via OAUTH or SDK is required.
iFrame SDK - This is to allow apps to interact with Hootsuite.com functions, built within the Hootsuite Ecosystem SDK. Access token required.

Step 1: Apply to Become a Developer

Before you start building an App, you'll need to register to become a Hootsuite Developer. Make sure you've read through the following terms of service:

Hootsuite API Terms of Service

After you have read the terms of service, Join our Developer Community. An active Hootsuite account is required to do this. If you do not already have a Hootsuite Account, register for our Hootsuite Developer account here. You'll be notified by email when your account has been approved.

Step 2: Domain Setup

Apps need to be hosted on servers that support https, so you'll need to set up the domain where your app will be hosted and get a SSL certificate. For development purposes, this can be your local machine, for example https://localhost).

If you don't have a server to host your App, we recommend using Heroku, fly.io, Glitch or Vercel as a hosting solution.

Step 3: Download Demo App

We have a boiler plate setup that provide a working baseline for the look and feel of the App stream, plugin, and content source extensions.

Step 4: App Configuration

Once your account is setup, you will need to configure your App in My Apps. Apps are comprised of one or more App extensions that represent different ways in which users can interact with your App.

There are two steps to configuring your App, which are listed below:

Retrieve and store your SDK API Key
Create your first app extension, a Stream for example

Step 5: Add a redirect/callback URI

Hootsuite requires you to provide us with your redirect/callback URI to register it to your app. Please go to https://dev-community.hootsuite.com/hc/en-us to submit a request.

Step 6: Retrieve your access token

Within My Apps, click on your default App to access your App information, which includes your API Client Key and Secret. Use these credentials to obtain the access token. An access token is required to access all of the REST API functions. Learn how to get the access token from a Hootsuite user:

REST API: https://apidocs.hootsuite.com/docs/api/index.html#operation/oauth2Token

SDK: https://apps.hootsuite.com/docs/sdk/4.1.1/global.html#getAuth

Step 7: Retrieve Your Access Token

Within My Apps, click on your default App to access your App information, which includes your API Client Key and Secret. Use these credentials to obtain the access token. An access token is required to access all of the REST API functions.

For an application that acts on behalf of a specific member (a Member App), you can use the member_app grant type, passing the member's unique identifier in the request body.

Using the `oauth2Token` Endpoint (`member_app` Grant)

Make a POST request to the OAuth2 Token endpoint.

Parameter	Value	Source	Description
`grant_type`	`member_app`	API Docs	The grant type for retrieving a token on behalf of a single member.
`client_id`	`CLIENT_ID`	Step 6	The public identifier for your application.
`client_secret`	`CLIENT_SECRET`	Step 6	The secret key for your application.
`member_id`	`MEMBER_ID`	API Call	The member ID of the user to grant a token for.

🔑 `curl` Command Example

Use the following command, replacing the variable names with your actual credentials:

curl -X POST \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=member_app&member_id=MEMBER_ID" \
  "https://platform.hootsuite.com/oauth2/token"

✅ Expected Response

A successful request (HTTP 200 OK) will return a JSON object containing your access token:

{
  "access_token": "YOUR_MEMBER_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "offline"
}

The value of "access_token" is the Bearer token you will use in the Authorization header for subsequent API requests acting on behalf of that member.

📘
Uninstall Callback
Hootsuite supports a URL callback to a specified endpoint when any user uninstalls your App.
You can configure your Uninstall Callback URL in your app settings. The callback request is a POST request with an application/x-www-form-urlencoded body and contains the following parameters:

Parameter Name Description
i User ID The ID of the user who uninstalled the application.
ts Timestamp The time the uninstall event occurred.
token Token A signature token to verify the authenticity of the callback request.
Example Method of Using the Uninstall Callback URL
JavaScript (Express/Node.js Example using query parameters for simplicity, though POST body access is recommended for production):
console.log(req.query.i); // User Id
console.log(req.query.ts); // Timestamp
console.log(req.query.token); // Token
PHP:
<?php
	$i = $_POST['i']; // Retrieve User ID from POST body
	$ts = $_POST['ts']; // Retrieve Timestamp from POST body
	$token = $_POST['token']; // Retrieve Token from POST body
?>