openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access 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: Access Tokens
  description: Operations for retrieving and validating OAuth access token metadata
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'
components:
  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: user@example.com
        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
    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
    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
  parameters:
    AccessTokenPath:
      name: token
      in: path
      required: true
      description: The OAuth access token to retrieve metadata for
      schema:
        type: string
      example: CKDZpunPLhICAQEYs-gDIIGOBii1hQIyGQAf3xBKEgsYjYMJVvlHEz9tFHAwSq1TQAM40s0D
    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
  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
    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: user@example.com
        hub_domain: demo.hubspot.com
        scopes:
        - contacts
        - content
        token_type: access
        expires_in: 1800
    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
  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