---
title: "Introspect Token"
method: POST
path: "/api/v1/oauth/introspect"
tags: ["oauth2-server"]
---

# Introspect Token

`POST /api/v1/oauth/introspect`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/oauth/introspect`
- Auth: none declared

Token Introspection endpoint (RFC 7662).

Issue #157: MCP SDK compliance - Token Introspection.

The caller must authenticate as a confidential OAuth client, with HTTP
Basic (``client_secret_basic``) or ``client_id`` + ``client_secret`` in
the form (``client_secret_post``) (RFC 7662 §2.1, #1741). Anyone else,
including a public client, gets ``401 invalid_client``. A client learns
about its own tokens only: a token issued to another client, like an
unknown, expired or revoked one, is ``{"active": false}``.

Args:
    request: FastAPI request (Authorization header, caller IP logging)
    token: Access token to introspect
    client_id: Caller's client_id for ``client_secret_post``
    client_secret: Caller's secret for ``client_secret_post``

Returns:
    Token metadata if active and issued to the caller, else
    ``{"active": false}``; a 401 error response when the caller is not
    an authenticated confidential client.

Example:
    POST /api/v1/oauth/introspect
    Authorization: Basic <base64(client_id:client_secret)>
    Content-Type: application/x-www-form-urlencoded

    token=mcp_abc123...

Spec: RFC 7662 - OAuth 2.0 Token Introspection

## Response `200`

Successful Response

- TokenIntrospectionResponse: OAuth 2.0 Token Introspection Response (RFC 7662). Issue #157: Type-safe response model for /introspect endpoint. Attributes: active: Whether token is active client_id: Client identifier (if active) scope: Granted scopes (if active) exp: Expiration timestamp (if active) iat: Issued-at timestamp (if active) token_type: Token type (if active) aud: Audience/Resource (RFC 8707, if present)
  - `active` boolean, required
  - `client_id` string, nullable
  - `scope` string, nullable
  - `exp` integer, nullable
  - `iat` integer, nullable
  - `token_type` string, nullable
  - `aud` string, nullable

## Other responses

- `400`: Two client authentication methods in one request
- `401`: Missing or invalid client credentials, or a public client (``invalid_client``)
- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)