HubSpot OAuth API

openapi: 3.1.0
info:
  title: HubSpot OAuth API
  description: |
    The HubSpot OAuth API enables secure authentication and authorization for accessing HubSpot resources.
    Use these endpoints to manage OAuth tokens, refresh access tokens, and retrieve token metadata for
    integrations with the HubSpot platform.
  version: 1.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server
tags:
- name: Access Tokens
  description: Operations for retrieving and validating OAuth access token metadata
- name: Refresh Tokens
  description: Operations for managing OAuth refresh tokens
- name: Token Management
  description: Operations for creating, refreshing, and managing OAuth tokens
paths:
  /oauth/v1/access-tokens/{token}:
    get:
      tags:
      - Access Tokens
      summary: Hubspot Retrieve Access Token Metadata
      description: |
        Retrieves metadata for a specific OAuth access token, including associated scopes,
        expiration time, and the user and hub information linked to the token.
      operationId: getAccessTokenMetadata
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          def result = "AccessTokenMetadataSuccessExample"
          return result
      parameters:
      - $ref: '#/components/parameters/AcceptHeader'
        example: example-value
      - $ref: '#/components/parameters/AccessTokenPath'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved access token metadata
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenMetadata'
              examples:
                AccessTokenMetadataSuccessExample:
                  $ref: '#/components/examples/AccessTokenMetadataSuccessExample'
        '401':
          description: Unauthorized - Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
  /oauth/v1/refresh-tokens/{token}:
    get:
      tags:
      - Refresh Tokens
      summary: Hubspot Retrieve Refresh Token Metadata
      description: |
        Retrieves metadata for a specific OAuth refresh token, including the associated
        client, user, and hub information.
      operationId: getRefreshTokenMetadata
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          def result = "RefreshTokenMetadataSuccessExample"
          return result
      parameters:
      - $ref: '#/components/parameters/AcceptHeader'
        example: example-value
      - $ref: '#/components/parameters/RefreshTokenPath'
        example: example-value
      responses:
        '200':
          description: Successfully retrieved refresh token metadata
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenMetadata'
              examples:
                RefreshTokenMetadataSuccessExample:
                  $ref: '#/components/examples/RefreshTokenMetadataSuccessExample'
        '401':
          description: Unauthorized - Invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
    delete:
      tags:
      - Refresh Tokens
      summary: Hubspot Revoke a Refresh Token
      description: |
        Revokes a specific OAuth refresh token, invalidating it and any associated access tokens.
        Use this endpoint when a user logs out or when you need to terminate a session.
      operationId: revokeRefreshToken
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          def result = "RefreshTokenRevokedSuccessExample"
          return result
      parameters:
      - $ref: '#/components/parameters/RefreshTokenPath'
        example: example-value
      responses:
        '204':
          description: Refresh token successfully revoked
        '401':
          description: Unauthorized - Invalid refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
  /oauth/v1/token:
    post:
      tags:
      - Token Management
      summary: Hubspot Create or Refresh an Access Token
      description: |
        Exchanges an authorization code for an access token or refreshes an existing access token
        using a refresh token. This endpoint supports multiple grant types including authorization_code
        and refresh_token flows.
      operationId: createOrRefreshAccessToken
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          def result = "TokenResponseSuccessExample"
          return result
      parameters:
      - $ref: '#/components/parameters/ContentTypeFormHeader'
        example: example-value
      - $ref: '#/components/parameters/AcceptHeader'
        example: example-value
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            examples:
              RefreshTokenRequestExample:
                $ref: '#/components/examples/RefreshTokenRequestExample'
              AuthorizationCodeRequestExample:
                $ref: '#/components/examples/AuthorizationCodeRequestExample'
      responses:
        '200':
          description: Successfully created or refreshed access token
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                TokenResponseSuccessExample:
                  $ref: '#/components/examples/TokenResponseSuccessExample'
        '400':
          description: Bad Request - Invalid grant or missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                BadRequestErrorExample:
                  $ref: '#/components/examples/BadRequestErrorExample'
        '401':
          description: Unauthorized - Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UnauthorizedErrorExample:
                  $ref: '#/components/examples/UnauthorizedErrorExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                InternalServerErrorExample:
                  $ref: '#/components/examples/InternalServerErrorExample'
components:
  parameters:
    AcceptHeader:
      name: Accept
      in: header
      description: The media type the client is willing to accept in the response
      schema:
        type: string
        default: application/json
      example: application/json
    ContentTypeFormHeader:
      name: Content-Type
      in: header
      description: The media type of the request body
      schema:
        type: string
        default: application/x-www-form-urlencoded
      example: application/x-www-form-urlencoded
    AccessTokenPath:
      name: token
      in: path
      required: true
      description: The OAuth access token to retrieve metadata for
      schema:
        type: string
      example: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
    RefreshTokenPath:
      name: token
      in: path
      required: true
      description: The OAuth refresh token
      schema:
        type: string
      example: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
  schemas:
    AccessTokenMetadata:
      type: object
      description: Metadata associated with an OAuth access token
      required:
      - token
      - app_id
      - hub_id
      - scopes
      - token_type
      - expires_in
      properties:
        token:
          type: string
          description: The access token string
          example: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
        app_id:
          type: integer
          description: The ID of the HubSpot application associated with this token
          example: 456789
        hub_id:
          type: integer
          description: The HubSpot portal (hub) ID associated with this token
          example: 62515
        user_id:
          type: integer
          description: The ID of the user who authorized the token
          example: 123456
        user:
          type: string
          description: The email address of the user who authorized the token
          example: [email protected]
        hub_domain:
          type: string
          description: The domain of the HubSpot portal
          example: demo.hubspot.com
        scopes:
          type: array
          description: List of scopes granted to this token
          items:
            type: string
          example:
          - contacts
          - content
        token_type:
          type: string
          description: The type of token (always 'access')
          example: access
        expires_in:
          type: integer
          description: Number of seconds until the token expires
          example: 1800
    RefreshTokenMetadata:
      type: object
      description: Metadata associated with an OAuth refresh token
      required:
      - token
      - client_id
      - hub_id
      - scopes
      properties:
        token:
          type: string
          description: The refresh token string
          example: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
        client_id:
          type: string
          description: The client ID of the application
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        hub_id:
          type: integer
          description: The HubSpot portal (hub) ID associated with this token
          example: 62515
        user_id:
          type: integer
          description: The ID of the user who authorized the token
          example: 123456
        user:
          type: string
          description: The email address of the user who authorized the token
          example: [email protected]
        scopes:
          type: array
          description: List of scopes granted to this token
          items:
            type: string
          example:
          - contacts
          - content
    TokenRequest:
      type: object
      description: Request body for token creation or refresh
      required:
      - grant_type
      - client_id
      - client_secret
      properties:
        grant_type:
          type: string
          description: The type of grant being requested
          enum:
          - authorization_code
          - refresh_token
          example: refresh_token
        client_id:
          type: string
          description: The client ID of your application
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        client_secret:
          type: string
          description: The client secret of your application
          example: 12345678-abcd-efgh-ijkl-9876543210ab
        redirect_uri:
          type: string
          description: The redirect URI (required for authorization_code grant)
          example: https://myapp.example.com/oauth/callback
        code:
          type: string
          description: The authorization code (required for authorization_code grant)
          example: abc123def456
        refresh_token:
          type: string
          description: The refresh token (required for refresh_token grant)
          example: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
    TokenResponse:
      type: object
      description: Response containing the new access token and related information
      required:
      - access_token
      - token_type
      - expires_in
      - refresh_token
      properties:
        access_token:
          type: string
          description: The new access token
          example: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
        token_type:
          type: string
          description: The type of token (always 'bearer')
          example: bearer
        expires_in:
          type: integer
          description: Number of seconds until the access token expires
          example: 1800
        refresh_token:
          type: string
          description: The refresh token for obtaining new access tokens
          example: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
        id_token:
          type: string
          description: The ID token (only returned if openid scope was requested)
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
    Error:
      type: object
      description: Standard error response object
      required:
      - category
      - correlationId
      - message
      properties:
        category:
          type: string
          description: The category of the error
          example: VALIDATION_ERROR
        correlationId:
          type: string
          format: uuid
          description: A unique identifier for tracking this error
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message:
          type: string
          description: A human-readable error message
          example: Invalid refresh token
        subCategory:
          type: string
          description: A more specific error category
          example: INVALID_TOKEN
        context:
          type: object
          description: Additional context about the error
          additionalProperties:
            type: array
            items:
              type: string
          example:
            invalidToken:
            - The provided token is invalid or expired
        links:
          type: object
          description: Links to relevant documentation
          additionalProperties:
            type: string
          example:
            knowledge-base: https://developers.hubspot.com/docs/api/oauth
        errors:
          type: array
          description: List of specific errors
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example:
          - message: Invalid parameter value
            code: INVALID_PARAMETER
            subCategory: MISSING_REQUIRED_FIELD
            in: body
            context: &id001
              missingFields:
              - client_secret
    ErrorDetail:
      type: object
      description: Detailed information about a specific error
      required:
      - message
      properties:
        message:
          type: string
          description: A human-readable error message
          example: Invalid parameter value
        code:
          type: string
          description: An error code
          example: INVALID_PARAMETER
        subCategory:
          type: string
          description: A specific error subcategory
          example: MISSING_REQUIRED_FIELD
        in:
          type: string
          description: The location of the error (e.g., body, query, path)
          example: body
        context:
          type: object
          description: Additional context about the specific error
          additionalProperties:
            type: array
            items:
              type: string
          example: *id001
  examples:
    AccessTokenMetadataSuccessExample:
      summary: Successful access token metadata retrieval
      description: Example response when successfully retrieving access token metadata
      value:
        token: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
        app_id: 456789
        hub_id: 62515
        user_id: 123456
        user: [email protected]
        hub_domain: demo.hubspot.com
        scopes:
        - contacts
        - content
        token_type: access
        expires_in: 1800
    RefreshTokenMetadataSuccessExample:
      summary: Successful refresh token metadata retrieval
      description: Example response when successfully retrieving refresh token metadata
      value:
        token: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
        client_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        hub_id: 62515
        user_id: 123456
        user: [email protected]
        scopes:
        - contacts
        - content
    TokenResponseSuccessExample:
      summary: Successful token response
      description: Example response when successfully creating or refreshing an access token
      value:
        access_token: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
        token_type: bearer
        expires_in: 1800
        refresh_token: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
    RefreshTokenRequestExample:
      summary: Refresh token request
      description: Example request body for refreshing an access token
      value:
        grant_type: refresh_token
        client_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        client_secret: 12345678-abcd-efgh-ijkl-9876543210ab
        refresh_token: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
    AuthorizationCodeRequestExample:
      summary: Authorization code request
      description: Example request body for exchanging an authorization code
      value:
        grant_type: authorization_code
        client_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        client_secret: 12345678-abcd-efgh-ijkl-9876543210ab
        redirect_uri: https://myapp.example.com/oauth/callback
        code: abc123def456
    UnauthorizedErrorExample:
      summary: Unauthorized error response
      description: Example error response for unauthorized requests
      value:
        category: UNAUTHORIZED
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: Invalid or expired token
        subCategory: INVALID_TOKEN
    BadRequestErrorExample:
      summary: Bad request error response
      description: Example error response for invalid requests
      value:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: Missing required parameter
        subCategory: MISSING_PARAMETER
        errors:
        - message: The 'client_secret' parameter is required
          code: MISSING_REQUIRED_FIELD
          in: body
    InternalServerErrorExample:
      summary: Internal server error response
      description: Example error response for server errors
      value:
        category: SERVER_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: An unexpected error occurred
        links:
          knowledge-base: https://developers.hubspot.com/docs/api/oauth