openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Refresh Tokens API
  description: "The HubSpot Analytics Events API allows you to retrieve event completion data \nfrom your HubSpot account. Use this API to query event instances associated with \nCRM objects, filter by event types, and analyze user behavior and engagement patterns.\n\n## Key Features\n- Retrieve event instances for CRM objects\n- Filter events by type, date range, and object\n- Paginate through large result sets\n- Query available event types\n"
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server
tags:
- name: Refresh Tokens
  description: Operations for managing OAuth refresh tokens
paths:
  /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'
components:
  schemas:
    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:
            missingFields:
            - client_secret
    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: user@example.com
        scopes:
          type: array
          description: List of scopes granted to this token
          items:
            type: string
          example:
          - contacts
          - content
    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:
              missingFields:
              - client_secret
  examples:
    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
    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: user@example.com
        scopes:
        - contacts
        - content
    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
  parameters:
    RefreshTokenPath:
      name: token
      in: path
      required: true
      description: The OAuth refresh token
      schema:
        type: string
      example: 6f18f26a-3e95-4d95-a6e5-3d5c6e5c9e5a
    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
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            analytics.read: Read analytics data