---
title: "Token introspection endpoint"
method: POST
path: "/oauth/2026-03/token/introspect"
tags: ["Advanced"]
---

# Token introspection endpoint

`POST /oauth/2026-03/token/introspect`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/oauth/2026-03/token/introspect`
- Auth: none declared

Returns validity and metadata for access and refresh tokens.

## Request body `application/x-www-form-urlencoded`

- object
  - `client_id` string
  - `client_secret` string
  - `token` string
  - `token_type_hint` string

## Response `200`

successful operation

- union
  - object
    - `active` boolean, required: A boolean indicating whether the token is currently active.
    - `app_id` integer, required: An integer representing the unique identifier of the application associated with the token.
    - `client_id` string, required: A string representing the client ID associated with the token.
    - `expires_in` integer, required: An integer in int64 format representing the time in seconds until the token expires.
    - `hub_domain` string: A string representing the domain of the HubSpot account associated with the token.
    - `hub_id` integer, required: An integer representing the unique identifier of the HubSpot account (hub) associated with the token.
    - `is_private_distribution` boolean, required: A boolean indicating whether the token is for private distribution.
    - `scopes` string[], required: An array of strings representing the scopes (permissions) granted to the token.
    - `signed_access_token` SignedAccessToken, required
      - `appId` integer, required: An integer identifying the application that issued the token.
      - `appInstallId` string, required: A string identifying the installation instance of the application associated with the token.
      - `audience` string, required: A string representing the intended audience for the token.
      - `expiresAt` integer, required: An integer representing the expiration time of the token, in Unix timestamp format.
      - `hubId` integer, required: An integer identifying the HubSpot account associated with the token.
      - `hublet` string, required: A string indicating the specific HubSpot region or cluster.
      - `installingUserId` integer, required: An integer identifying the user who installed the application associated with the token.
      - `isPrivateDistribution` boolean, required: A boolean indicating whether the token is for a private distribution of the application.
      - `isServiceAccount` boolean, required: A boolean indicating whether the token is for a service account.
      - `isUserLevel` boolean, required: A boolean indicating whether the token is associated with a user-level scope.
      - `newSignature` string, required: A string representing a new cryptographic signature for the token.
      - `scopeToScopeGroupPks` string, required: A string mapping scopes to their respective scope group primary keys.
      - `scopes` string, required: A string detailing the permissions granted by the token.
      - `signature` string, required: A string representing the cryptographic signature of the token.
      - `trialScopeToScopeGroupPks` string, required: A string mapping trial scopes to their respective scope group primary keys.
      - `trialScopes` string, required: A string detailing the trial permissions granted by the token.
      - `userId` integer, required: An integer identifying the user associated with the token.
    - `token` string, required: A string representing the token itself.
    - `token_type` string, required: A string representing the type of the token.
    - `token_use` 'access_token', required: A string indicating the use of the token, which defaults to 'access_token'.
    - `user` string: A string representing the username associated with the token.
    - `user_id` integer, required: An integer representing the unique identifier of the user associated with the token.
  - object
    - `active` boolean, required: A boolean indicating whether the token is currently active.
    - `app_id` integer, required: An integer representing the unique identifier of the application associated with the token.
    - `client_id` string, required: A string representing the unique identifier of the client that requested the token.
    - `hub_domain` string: A string representing the domain of the HubSpot account associated with the token.
    - `hub_id` integer, required: An integer representing the unique identifier of the HubSpot account associated with the token.
    - `scopes` string[], required: An array of strings representing the scopes associated with the token.
    - `token` string, required: The string representation of the refresh token.
    - `token_type` string, required: A string indicating the type of the token.
    - `token_use` 'refresh_token', required: Indicates the use of the token, which is 'refresh_token' by default.
    - `user` string: A string representing the user associated with the token.
    - `user_id` integer, required: An integer representing the unique identifier of the user associated with the token.

## Other responses

- `default`: An error occurred.

## Changes

- **2026-06-15** (2026-03) `03dfd4737244`: 2 breaking, 1 warning, 1 info
  - added `#/components/schemas/PublicAccessTokenInfoResponse, #/components/schemas/PublicRefreshTokenInfoResponse` to the response body `oneOf` list for the response status `200`
  - the response's body type changed from `object` to no type for status `200`
  - removed the optional property `active` from the response with the `200` status
  - removed response discriminator for the response status `200`
- **2026-06-15** (2026-03) `33cdb28eb03d`: 1 breaking, 3 info
  - the response's body type changed from no type to `object` for status `200`
  - added response discriminator for the response status `200`
  - removed `#/components/schemas/PublicAccessTokenInfoResponse, #/components/schemas/PublicRefreshTokenInfoResponse` from the response body `oneOf` list for the response status `200`
  - added the optional property `active` to the response with the `200` status
- **2026-06-05** (2026-03) `03dfd4737244`: 2 info
  - the response property `oneOf[#/components/schemas/PublicAccessTokenInfoResponse]/signed_access_token/appInstallId` became required for the status `200`
  - the response property `oneOf[#/components/schemas/PublicAccessTokenInfoResponse]/signed_access_token/audience` became required for the status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/hubspot/apis/auth-oauth/changes/oauth/2026-03/token/introspect/post.md)

---

[API](https://skmtc.dev/hubspot/apis/auth-oauth.md) - [All operations](https://skmtc.dev/hubspot/apis/auth-oauth/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/auth-oauth/revisions/976a8e400266?raw)