Authentication

Hootsuite uses OAuth 2.0 to authenticate & authorize end users to use your application. Users authenticated with the Hootsuite API are subject to the same permissions configured in the Hootsuite Web Dashboard. Learn more about managing permissions at the Hootsuite Help Center.

Hootsuite supports the following OAuth2 Grant Types:

  • Authorization Code for apps running on a web server.
  • Refresh Token for apps to refresh access tokens.

Hootsuite also supports two custom Grant Types:

  • member_app to access APIs on behalf of a member that has installed the app
  • organization_app to access APIs on behalf of an organization that has installed the app

Please note that our custom Grant Types are for member or organization apps that have been installed to a Hootsuite users account or organization, respectively.

Authorization Code Workflow

  1. Your application sends a request to the Authorize endpoint with the required parameters (client_id, response_type=code, redirect_uri and scope). The Hootsuite OAuth2 API will return HTML to authenticate the user.
  2. The end user enters their username and password into the HTML form provided.
  3. The end user is successfully authorized and then redirected to the redirect URI specified in Step 1.
  4. A code parameter will be appended to the redirect URI by the Hootsuite OAuth2 API.
  5. Your application makes a request to the Token endpoint with the required parameters (including code from the previous step).
  6. The Hootsuite OAuth2 API grants an access_token that can be used for future API requests.
  7. When the access_token expires, your application makes a request to the Token endpoint with the refresh_token parameter in order to refresh access.

Refresh Workflow

  1. To refresh an expired access token, your application should make a request to the Token endpoint with the required parameters (grant_type=refresh_token and refresh_token=<previous refresh token>) and the basic auth header (client_id and client_secret)
  2. The Hootsuite OAuth2 API grants a new access_token that can be used for future API requests and a new refresh_token for requesting a future access token. Note that refresh tokens don't have an expiry but can only be used once.

member_app Custom Grant Workflow

The member_app grant type can only be used to authenticate Hootsuite users who have your App installed. The SDK will provide the member_id (i.e. user_id) information via the SDK Authentication.
For private Apps, you can retrieve your member_id via one of the following methods:

  • Use the built-in OAuth in Postman, authenticate with the Authorization code grant type, and then retrieve your member_id details. This workflow is detailed here.
  • If you have an Organization > click "Members" and the URL in your browser will show your member_id.
  1. Your application makes a request to the Token endpoint with the required parameters (grant_type=member_app, member_id=<member who has the app installed>) and the basic auth header (client_id and client_secret)
  2. The Hootsuite API returns with an access_token that can be used to access APIs on behalf of a member that has installed the app.

organization_app Custom Grant Workflow

The organization_app grant type can only be used to authenticate a Hootsuite Organization that has your App installed. Organizations used for prescreen components must be on the Enterprise plan, and the Organization App installation must be configured by Hootsuite.

  1. Your application makes a request to the Token endpoint with the required parameters (grant_type=organization_app, organization_id=<organization that has the app installed>) and the basic auth header (client_id and client_secret)
  2. The Hootsuite API returns with an access_token that can be used to access APIs on behalf of a organization that has installed the app.

Authentication


Suggested Edits are limited on API Reference Pages

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