I was trying to implement a token introspection endpoint with the following flavor:

• For debuggability, I wanted to return metadata about tokens that are expired now but were once valid. I acknowledge that this is discouraged (SHOULD NOT) in https://datatracker.ietf.org/doc/html/rfc7662.
• I wanted to return metadata about refresh tokens, but with "active": false to prevent downstream resource servers from misinterpreting them as valid access tokens. (The RFC leaves it unclear how the token introspection endpoint ought to distinguish refresh tokens from access tokens. This was just my guess. Maybe there's a better way.)

Here was my implementation attempt, which has a bug:

class RequestValidator(oauthlib.oauth2.RequestValidator):
    ...
    
    def introspect_token(
        self,
        token: str,
        token_type_hint: str | None,
        request: oauthlib.common.Request,
    ) -> dict[str, str] | None:
        """Return information about an access or refresh token (if it exists)."""
        found_token_info = ...   # Implementation omitted.

        if found_token is None:
            return None
        else:
            active = (
                found_token_info.type == "access"  # not "refresh"
                and found_token.expires_at > datetime.now()
            )
            return {
                "active": active  # <-- Bug!
                "scope": found_token_info.scope,
                "username": found_token_info.username,
            }

The bug in that code is that returning active: False does not actually do anything. oauthlib always overrides active to True. The only way to return "active": false over HTTP is for the Python code to return None.

That wasn't clear in the oauthlib documentation, so this updates it.

(Documentation aside, I think this behavior is unfortunate because it prevents us from deliberately returning extra information about inactive tokens, but maybe that's just a bad thing to want to do.)