How to Authenticate via cURL

Our Getting Started guide outlines how to set up the Authorization Code workflow using Postman's built-in OAuth. If, however, you need to test the 3-legged flow end-to-end, you can use cURL and your browser to receive a code and exchange it for a token! Here are the steps:

Authorization Flow:

  1. In a browser paste the following URL:
    https://platform.hootsuite.com/oauth2/auth?response_type=code&client_id=<YOUR_CLIENT_ID>&redirect_uri=<YOUR_REDIRECT_URI>
  2. If you're not already logged into your Hootsuite account, you will be prompted to enter your Hootsuite credentials. If you are logged in, you'll automatically be redirected to the consent page.
  3. Before moving forward, open the Console, go to the Network tab, and ensure “Preserve Log” is on. Click “Allow”
  4. In the Network tab, you will eventually see a redirect (302) to the redirect URI. While the browser will most likely show a blank webpage, it is important to look at the URL you've been redirected to, as it will contain the “code” parameter.
  5. Copy the URL (it will look something like this:
    https://app.getpostman.com/oauth2/callback?code=Jzzb9OIfh1-L2LtDVY9RUQynm3z-8SSeEGQE9oYDnRI.4r1jWK2smtOiQfcuucUqWn2edsqR0tc6orx4QQH_3kU&scope=offline).
  6. Copy the code=<CODE> portion

Token Flow:

  1. Using curl, execute the following call (do it quickly, you only have 10 minutes before the code expires)
curl -v -H "Content-Type: application/x-www-form-urlencoded" 
-u <CLIENT_ID>:<CLIENT_SECRET> \
-d code=<CODE_FROM_BEFORE> \
-d grant_type=authorization_code 
-d redirect_uri=<REDIRECT_URI> \
-X POST https://platform.hootsuite.com/oauth2/token
  1. The API will return a Bearer Token (access_token) and other related information:
{
"access_token":"LAj5ue5hvUzaFQvrHkj5kSbHGeRywOYonYZ4nKuvvGg.OB-yOXdkJFHuvEmpAFR7U3nm0MSKJ_9HmrFvKMN4Q2o",
"expires_in":3599,
"refresh_token":"2lVFWjxuXn7XMp_IKQGsktgFO3etqcNSsoAcJDDASNc.KsoN3Ot1saxo70kG1qmcDrnRJRIonK4mWzJTagtaL8Q",
"scope":"offline",
"token_type":"bearer"
}
  1. You can now use the Bearer (access_token) to make API calls on behalf of the authenticated user.

*To Authenticate via our other grant_types, see our API Authentication Guide here.

Authentication Errors

"unknown_redirect_uri - redirect_uri parameter not registered with client's redirect url(s)"

  • The API Callback URL, aka redirect_uri, must be configured in Hootsuite's backend. Please email us with your client_id and redirect_uri to be configured. Note that the redirect_uri must start with https:// or http://localhost.

"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed"

  • Ensure that the Authorization header includes the word Basic and that your client_id and client_secret are base-64 encoded.
  • The code provided could be expired (it expires after 10 minutes). Try retrieving a new code.
  • The parameters being sent need to be Content-Type: application/x-www-form-urlencoded

"Invalid memberId”

  • Ensure you are using the correct grant_type. We only support 2 main grant types (authorization_code and refresh_token) and 2 custom grant types (member_app and organization_app). To see an in-depth explanation of our authentication methods, see our guide here.

"The request could not be authorized" when using member_app grant type

  • The user you are attempting to authenticate (provided via the member_id parameter) must have your App installed.

Errors scheduling messages

I've included an attached image or video, but I'm getting a "5000 unknown error"

  • Depending on the file size, it can take some time for the uploaded image or video to finish processing. If you get an error when including a newly uploaded image or video, it could be because the file hasn't been fully processed. Call the retrieve media upload status endpoint to ensure your file state is READY before including it in your message.

Getting a "This social profile type is not supported by our API at this time" error

  • This error will appear if you are attempting to send or schedule a message to an Instagram Business Profile. Instagram Business Profiles are not currently supported through our REST API, but you can still schedule messages to Instagram Personal Profiles.

Errors retrieving information about Members, Teams, or Social Profiles

"Insufficient permissions to view [team] / [organization members] / [etc]" OR "Not authorized to make changes to organization" errors

  • Authenticated user does not have the correct Permissions within the Hootsuite Organization to view/make changes to other Members/Teams/Social Profiles. For a list of the minimum permissions needed to call the various endpoints, see our Permissions Matrix here.