fastmcp.server.auth.providers.introspection

OAuth 2.0 Token Introspection (RFC 7662) provider for FastMCP.

This module provides token verification for opaque tokens using the OAuth 2.0 Token Introspection protocol defined in RFC 7662. It allows FastMCP servers to validate tokens issued by authorization servers that don't use JWT format.

Example: ```python from fastmcp import FastMCP from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier

# Verify opaque tokens via RFC 7662 introspection
verifier = IntrospectionTokenVerifier(
    introspection_url="https://auth.example.com/oauth/introspect",
    client_id="your-client-id",
    client_secret="your-client-secret",
    required_scopes=["read", "write"]
)

mcp = FastMCP("My Protected Server", auth=verifier)
```

Classes

IntrospectionTokenVerifier ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/introspection.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

OAuth 2.0 Token Introspection verifier (RFC 7662).

This verifier validates opaque tokens by calling an OAuth 2.0 token introspection endpoint. Unlike JWT verification which is stateless, token introspection requires a network call to the authorization server for each token validation.

The verifier authenticates to the introspection endpoint using either:

• HTTP Basic Auth (client_secret_basic, default): credentials in Authorization header
• POST body authentication (client_secret_post): credentials in request body

Both methods are specified in RFC 6749 (OAuth 2.0) and RFC 7662 (Token Introspection).

Use this when:

• Your authorization server issues opaque (non-JWT) tokens
• You need to validate tokens from Auth0, Okta, Keycloak, or other OAuth servers
• Your tokens require real-time revocation checking
• Your authorization server supports RFC 7662 introspection

Caching is disabled by default to preserve real-time revocation semantics. Set cache_ttl_seconds to enable caching and reduce load on the introspection endpoint (e.g., cache_ttl_seconds=300 for 5 minutes).

Methods:

verify_token ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/src/fastmcp/server/auth/providers/introspection.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

verify_token(self, token: str) -> AccessToken | None

Verify a bearer token using OAuth 2.0 Token Introspection (RFC 7662).

This method makes a POST request to the introspection endpoint with the token, authenticated using the configured client authentication method (client_secret_basic or client_secret_post).

Results are cached in-memory to reduce load on the introspection endpoint. Cache TTL and size are configurable via constructor parameters.

Args:

• token: The opaque token string to validate

Returns:

• AccessToken object if valid and active, None if invalid, inactive, or expired