The dual role is where it breaks. One class both mints and parses [5], so its constructor has to accept a plain claims dict; there is nothing to sign otherwise [13]. Pydantic cannot tell a dict your own code assembled from a dict that arrived over the wire, and FastAPI's job on a body parameter is precisely to build the annotated model out of untrusted JSON [14]. A signature check you can skip by not presenting a signature is an unusual kind of optional.
The switch that closes it is opt-in. Nothing refuses the dict path unless `model_config` names `verified_only=True`, so any model that omits the flag keeps the permissive constructor [19]. Version 0.2.0 documented the hazard and shipped it, and the author's own verdict is that documenting a hole is not fixing it [15]. Per-model opt-in is defensible here, because the same library has to serve the minting side, where a claims dict is the entire point [13].
The claim annotations are the part I would keep even if I skipped the package. `IssClaim` and `AudClaim` compare against a value you name [8], and they are ordinary `Annotated` metadata, so they compose with whatever else Pydantic does to that field, with `Claim` there to subclass for checks the library does not ship [9]. The author's framing of why `aud` gets skipped is the honest one: it is one more `if` [10]. In an annotation, omitting it means deleting a line that sits next to the field it protects.
Failure handling is the other thing that transfers. `ValidationError` and `PydanticCustomError` both subclass `ValueError`, so one `except` clause catches expired, forged and missing-claim tokens alike, and the error type still separates go-refresh from log-in-again [12].
Before putting this on an auth path I would want the token verified in more than one handler, so a single declaration pays for itself, and mypy running in CI, because without that a typed payload buys autocomplete rather than enforcement [17]. Accepting a library type on the boundary that decides caller identity is a heavier commitment than accepting one on a request body. The fix arrived the hard way: the author reports three attempts, and defining `__init__` on the model was among the two that failed [18].
