The photocopier decided our token format
A token is normally a security decision. This one was a printing decision.
We needed a QR on a school invoice that takes a parent straight to paying it. The orthodox choice is a signed JWT: it carries its own claims, verifies without a database lookup, and every backend engineer reaches for it. We used a twelve-character opaque string instead.
Here is why, measured rather than argued.
A QR code is text turned into squares, and more text means more squares. Since the printed code stays the same physical size, more squares means each one gets smaller.
- Our short token: a 29×29 grid.
- The JWT equivalent: 57×57.
At the 26mm square we print, that is roughly a quarter of the area per module. And the reader is not a studio scanner — it is a phone camera, in a bursar’s office with one window, pointed at a photocopy of a photocopy.
That gap is the whole product. A code that needs three attempts and good light is a code that gets abandoned, and an abandoned code means the parent walks away with an unpaid bill and a slightly worse opinion of the school.
The short token wins twice, incidentally. A JWT only looks scrambled — it is
encoded, not encrypted, and anyone can paste one into a website and read the
invoice ID and amount inside. Printing that on paper leaks a little about a
family. K7m2Qx9v is a cloakroom ticket: meaningless to a stranger, precise to
the cloakroom.
The lesson I want to keep: the physical medium reaches back and constrains your data structures. Nobody writes that in an architecture document.