Fetch an environment's recently revoked sessions
What makes revocation immediate instead of eventual.
A session JWT is verified offline — that is the whole point of JWKS — so nothing can recall one. Ending a session stops the next refresh, and the token already in somebody’s hand keeps verifying until its own exp. This document closes that gap: a verifier that holds a current copy refuses a revoked sid within the copy’s cache window rather than within the token’s lifetime.
It is the same kind of thing as JWKS and is used the same way — public, unauthenticated, addressed by the publishable key your config already holds, and polled on a schedule rather than called per request. Checking a token stays a set lookup against a document already in memory.
The response carries Cache-Control: public, max-age=15, stale-while-revalidate=900, stale-if-error=900 — the stale window covers a refetch that is slow and one that fails alike, because a document you cannot refresh is more useful than no document. Both numbers matter and both are restated in the body:
max_age_secondsis the bound you get. A revoked session stops verifying within it.window_secondsis how far back the document reaches. A copy older than that says nothing about the tokens alive now — discard it.
When you cannot fetch it, keep verifying. A revocation list that refuses every request whenever it is unreachable is a worse failure than the one it prevents: the correct degrade is back to the bound that always existed, the token’s own few minutes. @userkit/nextjs’s verifyContactToken implements exactly this and reports which of the three cases it was in.
No CORS on this route, deliberately: the caller is a server. A revocation decision made in a page is a revocation decision an attacker controls.
Rate limited to 600 requests per minute per IP — the loosest limit on this surface, because polling it is the intended use.
Path Parameters
uk_pk_live_… or uk_pk_test_…. The list is per environment, like the key that signed the token.
Response
The environment's recent revocations. An empty list is the normal answer and is not an error.
The sessions revoked in this environment recently enough that a session JWT naming one could still be alive. Kept deliberately small: an older revocation names no token anybody could still present, so it is dropped rather than accumulated — this is a short list, never a growing certificate revocation list.
Session ids. Match against a token's sid claim.
How far back this document reaches. A copy older than this says nothing about the tokens alive now — discard it rather than trust it.
How long a copy stays current. This is the bound the endpoint buys you: a revoked session stops verifying within this many seconds instead of within the token's full lifetime.