Entitlement tokens, explained
The mechanism that keeps your site up during our outage, and how to use it properly.
When we authorise a key we do not just say yes. We say yes in a signed, dated, portable form — an entitlement token — that your application can hold and re-check without asking us again.
What is in one
The key it was issued for, the domain it was issued to, when it was issued, when it stops being valid, and a signature over all of that.
Nothing secret. Nothing about your users. You can decode one and read it; that is fine, because the signature is what makes it trustworthy rather than the contents being hidden.
What it is for
Two things, and the second is the important one.
Fewer round trips. You are not calling us on every page load. You are calling us when the token you are holding is close to expiry. For most sites that turns thousands of calls a day into a handful.
Surviving our downtime. If we are unreachable, your application keeps running on the token it holds. Our outage is invisible to your users until the token lapses, which is days rather than minutes.
Verifying one
Check the signature against the public key from the docs, then check the expiry. Both, in that order.
An expired token with a valid signature is still expired. A fresh token with a bad signature was not issued by us. Neither check is sufficient alone, and doing them in the other order means you spend time validating something you were going to reject anyway.
Where to keep it
Somewhere shared, if you have more than one server. A token cached per-process means every process fetches its own, and you have multiplied your call volume by your worker count for no benefit.
Redis, memcached, or a row in your own database all work. What matters is that it outlives a single request and is visible to every process that needs it.
The mistake to avoid
Treating a refusal as a network failure and falling back to the cached token.
Those are different events:
- We answer and say no → the token is not renewed, the gate closes now.
- We do not answer at all → the cached token stands until it expires.
Conflating them means a revoked key keeps working for days, which defeats the one thing revocation exists to do. In code: catch the network error, do not catch the 403.
How long they last
Long enough that a normal outage is invisible. Short enough that revocation means something within a working week.
That is a deliberate trade rather than an accident, and it is the same trade as the thirty-day key window: every credential in this system has a life, because a credential with no life is one you can never really take back.