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

# Diz se um token de acesso ainda vale (RFC 7662), com a sessão viva

> RFC 7662: diz se o token de acesso ainda vale agora. Use quando precisar do corte imediato depois do logout, da troca de senha, do bloqueio ou da exclusão, em vez de confiar no JWT até o exp. Sempre 200. Exige uma chave secreta criada COM o escopo auth:token (chaves sem restrição não o têm).



## OpenAPI

````yaml /api-reference/openapi.json post /auth/introspect
openapi: 3.1.0
info:
  title: UNIFOKAL API
  version: v1
  summary: >-
    Verificação de identidade: sessão criada no servidor, jornada no widget,
    resultado no webhook.
  description: >-
    A versão vive no caminho (/v1); não existe header de versão. Adição
    compatível (campo, módulo ou chave nova) NÃO sobe a versão: ignore o que não
    conhecer. Todo erro tem a forma { error, message }: o código é estável, a
    mensagem não. Ids são prefixo + ULID. Webhooks são assinados (HMAC SHA-256
    no header X-IDSAAS-Signature, janela de 300s; o segredo é SEU, mínimo 32
    caracteres) e o header x-idsaas-event carrega o tipo do evento.
  termsOfService: https://unifokal.com/termos
  contact:
    name: UNIFOKAL
    url: https://docs.unifokal.com/
servers:
  - url: https://api.unifokal.com/v1
security: []
externalDocs:
  description: >-
    Documentação completa em https://docs.unifokal.com/. Briefing para agentes
    de IA em https://unifokal.com/llms.txt.
  url: https://docs.unifokal.com/
paths:
  /auth/introspect:
    post:
      summary: Diz se um token de acesso ainda vale (RFC 7662), com a sessão viva
      description: >-
        RFC 7662: diz se o token de acesso ainda vale agora. Use quando precisar
        do corte imediato depois do logout, da troca de senha, do bloqueio ou da
        exclusão, em vez de confiar no JWT até o exp. Sempre 200. Exige uma
        chave secreta criada COM o escopo auth:token (chaves sem restrição não o
        têm).
      operationId: introspectAuthToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthIntrospectRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthIntrospectRequest'
      responses:
        '200':
          description: O estado do token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthIntrospectResponse'
        '400':
          description: >-
            Códigos estáveis: invalid_json, validation_error. Ramifique pelo
            campo error, nunca pela mensagem.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - properties:
                      error:
                        enum:
                          - invalid_json
                          - validation_error
        '401':
          description: >-
            Códigos estáveis: invalid_api_key. Ramifique pelo campo error, nunca
            pela mensagem.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - properties:
                      error:
                        enum:
                          - invalid_api_key
        '403':
          description: >-
            Códigos estáveis: credential_type_not_allowed,
            organization_suspended, test_key_used_in_production,
            insufficient_scope, ip_not_allowed. Ramifique pelo campo error,
            nunca pela mensagem.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - properties:
                      error:
                        enum:
                          - credential_type_not_allowed
                          - organization_suspended
                          - test_key_used_in_production
                          - insufficient_scope
                          - ip_not_allowed
        '413':
          description: >-
            Códigos estáveis: payload_too_large. Ramifique pelo campo error,
            nunca pela mensagem.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - properties:
                      error:
                        enum:
                          - payload_too_large
        '429':
          description: >-
            Códigos estáveis: rate_limited. Ramifique pelo campo error, nunca
            pela mensagem.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - properties:
                      error:
                        enum:
                          - rate_limited
      security:
        - secretKey: []
components:
  schemas:
    AuthIntrospectRequest:
      type: object
      properties:
        token:
          type: string
          maxLength: 8192
        token_type_hint:
          type: string
          enum:
            - access_token
      required:
        - token
    AuthIntrospectResponse:
      type: object
      description: >-
        RFC 7662 2.2: token inativo, desconhecido, vencido, de outro ambiente,
        de sessão revogada, de usuário fora de active ou de cliente M2M revogado
        volta só {"active": false}.
      required:
        - active
      properties:
        active:
          type: boolean
        token_type:
          type: string
          const: Bearer
        sub:
          type: string
        client_id:
          type: string
        aud:
          type:
            - string
            - array
          items:
            type: string
        iss:
          type: string
        exp:
          type: integer
        iat:
          type: integer
        jti:
          type: string
        sid:
          type: string
          description: 'Só no token de usuário: a sessão (família) que segue viva.'
        scope:
          type: string
          description: Só no token M2M.
    ErrorEnvelope:
      type: object
      description: >-
        Todo erro da API tem exatamente esta forma. O campo error é um código
        estável (contrato); message é texto livre e pode mudar sem aviso.
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Código estável do erro. Ramifique por ele.
        message:
          type: string
          description: Texto explicativo. NÃO é contrato.
      additionalProperties: false
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: >-
        Chave secreta (unifokal_live_ em produção, unifokal_test_ no sandbox: 64
        hex mais CRC-32) no Authorization: Bearer. Só no seu servidor: nunca no
        browser ou app (o widget monta apenas com o id vs_ da sessão). Não
        existe chave publishable.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.