Hootsuite Authentication API

openapi: 3.2.0
info:
  description: '![Run in Postman](https://app.getpostman.com/run-collection/eeda0fcdf55ea26bd0ec#?env%5BHootsuite%5D=W3sidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJ1cmwiLCJ2YWx1ZSI6Imh0dHBzOi8vcGxhdGZvcm0uaG9vdHN1aXRlLmNvbSJ9LHsidHlwZSI6InRleHQiLCJlbmFibGVkIjp0cnVlLCJrZXkiOiJhdXRob3JpemF0aW9uX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi9hdXRoIn0seyJ0eXBlIjoidGV4dCIsImVuYWJsZWQiOnRydWUsImtleSI6InRva2VuX3VybCIsInZhbHVlIjoiaHR0cHM6Ly9wbGF0Zm9ybS5ob290c3VpdGUuY29tL29hdXRoMi90b2tlbiJ9LHs…'
  version: '1.0'
  title: Hootsuite REST Authentication API
  contact:
    email: dev.support@hootsuite.com
  license:
    name: Hootsuite Developer Terms and API License Agreement
    url: https://hootsuite.com/legal/dev-api-terms
servers:
- url: https://platform.hootsuite.com
security:
- OAuth2: []
tags:
- name: Authentication
  description: Hootsuite uses OAuth2 to authenticate end users. Members authenticated with the Hootsuite API are subject to the same permissions configured as when using the Hootsuite Web Dashboard. Learn more about managing permissions at the Hootsuite Help Center.
paths:
  /oauth2/auth:
    get:
      tags:
      - Authentication
      operationId: oauth2Authorize
      summary: OAuth2 Authorize
      description: OAuth2 Authorize endpoint.
      security: []
      parameters:
      - in: query
        name: response_type
        description: The response type requested.
        required: true
        schema:
          type: string
          enum:
          - code
      - in: query
        name: client_id
        required: true
        description: Your client ID found in the Hootsuite Developer Portal.
        schema:
          type: string
      - in: query
        name: scope
        required: false
        description: The required token scopes. Include "offline" if you need a refresh token or "analytics:read" for analytics API access. Multiple scopes must be separated by spaces.
        schema:
          type: string
          enum:
          - offline
          - analytics:read
      - in: query
        name: redirect_uri
        required: true
        description: The URI to redirect to after authentication.
        schema:
          type: string
      - in: query
        name: state
        required: true
        description: 'An opaque value used by the client to maintain state between the request and callback. See [rfc6749#section-4.1.1](https://tools.ietf.org/html/rfc6749#section-4.1.1) for more context.


          Note: this param is required and must be at least 8 characters long.

          '
        schema:
          type: string
      responses:
        '200':
          description: Success
  /oauth2/token:
    post:
      tags:
      - Authentication
      operationId: oauth2Token
      summary: OAuth2 Token
      description: 'OAuth2 Token endpoint. The required parameters depend on the grant type requested:


        |Required Parameter|Grant Type|

        |---|---|

        |code|authorization_code|

        |redirect_uri|authorization_code|

        |member_id|member_app|

        |organization_id|organization_app|

        |refresh_token|refresh_token|


        This endpoint requires that you pass in your client credentials using the HTTP Basic authentication scheme as per outlined in the spec.

        Including your client credentials in the request-body is not supported.


        **Note**: The specific authorization code provided for the `code` parameter must only be used successfully once. If an authorization code is used a second time, all tokens granted with the first `/oauth2/token` call will be revoked.'
      security:
      - Basic_Auth: []
      parameters:
      - in: header
        name: Authorization
        description: A base64-encoded client_id:client_secret string used for authentication.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  description: The OAuth2 grant_type used.
                  type: string
                  enum:
                  - authorization_code
                  - client_credentials
                  - member_app
                  - organization_app
                  - refresh_token
                code:
                  description: 'The authorization code granted by the /oauth2/auth endpoint. Required for grant type: authorization_code'
                  type: string
                redirect_uri:
                  description: 'The URI to redirect to after authentication. Required for grant type: authorization_code'
                  type: string
                member_id:
                  description: 'The member id of the user to grant a token for. Required for grant type: member_app'
                  type: string
                organization_id:
                  description: 'The organization id to grant a token for. Required for grant type: organization_app'
                  type: string
                refresh_token:
                  description: 'The refresh token code previously granted. Required for grant type: refresh_token'
                  type: string
              required:
              - grant_type
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/OAuth2BearerToken'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/OAuthError'
components:
  schemas:
    OAuth2BearerToken:
      type: object
      properties:
        access_token:
          type: string
          description: The access token.
          example: e9a90a81-xf2d-dgh3-cfsd-23jhvn76
        token_Type:
          type: string
          description: The access token type.
          example: Bearer
        expires_in:
          type: number
          description: The number of seconds until expiry
          example: 2592000
        refresh_token:
          type: string
          description: The refresh token.
          example: 82d82cf4-76gf-gfds-nt3k-lzpo12jg
        scope:
          type: string
          description: The scopes granted to this token.
          example: offline
    OAuthError:
      type: object
      properties:
        error:
          type: string
          description: An error code indicating the type of error that occurred. Should be used in conjunction with HTTP status.
          enum:
          - request_unauthorized
          - request_forbidden
          - invalid_request
          - unauthorized_client
          - access_denied
          - unsupported_response_type
          - invalid_scope
          - server_error
          - temporarily_unavailable
          - unsupported_grant_type
          - invalid_grant
          - invalid_client
          - unknown_error
          - not_found
          - invalid_state
          - misconfiguration
          - insufficient_entropy
          - invalid_token
          - token_signature_mismatch
          - token_expired
          - scope_not_granted
          - token_claim
          - token_inactive
        error_description:
          type: string
          description: A description of error.
          example: An error message
        error_hint:
          type: string
          description: A helpful hint about the error.
          example: '"Make sure that the various parameters are correct, be aware of case sensitivity and trim your parameters.'
        status_code:
          type: number
          description: The status code
          example: 400
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.hootsuite.com/oauth2/auth
          tokenUrl: https://platform.hootsuite.com/oauth2/token
          scopes:
            offline: Request refresh tokens
            analytics:read: Request analytics API access
    Basic_Auth:
      type: http
      scheme: basic
x-provenance:
  generated: '2026-08-13'
  method: searched
  source: https://apidocs.hootsuite.com/docs/api/swagger.yaml
  note: First-party Hootsuite REST API contract. Discovered from the ReDoc loader at https://platform.hootsuite.com/docs/api/index.html (spec-url ./swagger.yaml) and confirmed as the canonical service-desc link in Hootsuite's RFC 9727 API catalog at https://www.hootsuite.com/.well-known/api-catalog. Published as Swagger 2.0; converted to OpenAPI 3.0 with swagger2openapi 7 for this working copy. The verbatim Swagger 2.0 source is kept at openapi/_original/hootsuite-rest-api-swagger.yaml.
  ownership: host platform.hootsuite.com, info.title "Hootsuite REST API", contact dev.support@hootsuite.com - the contract identifies itself as Hootsuite's.