> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# Introspect a token

> RFC 7662 token introspection: the calling client authenticates (client_id, plus
client_secret for confidential clients) and submits a token to check, as form or
JSON. Returns active true only for a token that the authenticated client itself
issued and that is neither revoked nor expired, along with its scope, client_id,
username, token_type, exp, iat, and sub; for any other token (unknown, expired,
revoked, or belonging to a different client) it returns active false without leaking
details.

## Token introspection (RFC 7662)

Reports whether a token is currently active and returns its metadata (scope, expiry, subject). Send the token as a form field `token` (**`application/x-www-form-urlencoded`**). Returns `{ "active": false }` for unknown, expired, or revoked tokens.


## OpenAPI

````yaml POST /v1/oauth/introspect
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/oauth/introspect:
    post:
      tags:
        - auth
      summary: Introspect a token
      description: >-
        RFC 7662 token introspection: the calling client authenticates
        (client_id, plus

        client_secret for confidential clients) and submits a token to check, as
        form or

        JSON. Returns active true only for a token that the authenticated client
        itself

        issued and that is neither revoked nor expired, along with its scope,
        client_id,

        username, token_type, exp, iat, and sub; for any other token (unknown,
        expired,

        revoked, or belonging to a different client) it returns active false
        without leaking

        details.
      operationId: oauth_introspect
      requestBody:
        description: >-
          RFC 7662. The calling client authenticates (client_id + secret for
          confidential). Form or JSON.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntrospectReq'
        required: true
      responses:
        '200':
          description: 'Token metadata for a token this client issued, or { active: false }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntrospectResp'
        '401':
          description: Invalid client credentials
        '429':
          description: Too many requests (per-IP rate limit)
components:
  schemas:
    IntrospectReq:
      type: object
      required:
        - token
        - client_id
      properties:
        client_id:
          type: string
        client_secret:
          type:
            - string
            - 'null'
        token:
          type: string
        token_type_hint:
          type:
            - string
            - 'null'
    IntrospectResp:
      type: object
      required:
        - active
      properties:
        active:
          type: boolean
        client_id:
          type:
            - string
            - 'null'
        exp:
          type:
            - integer
            - 'null'
          format: int64
        iat:
          type:
            - integer
            - 'null'
          format: int64
        scope:
          type:
            - string
            - 'null'
        sub:
          type:
            - string
            - 'null'
        token_type:
          type:
            - string
            - 'null'
        username:
          type:
            - string
            - 'null'

````