Tokens That Expire

Tandem's ride-export endpoint works a little differently from the rest, and Jonas said so in the email: Vera's key gets her a token for that endpoint, and the token does the actual requests. Monday afternoon it went beautifully. She pulled a token, ran her exports, and saved the working command in her notes. Tuesday morning she pasted the same command back in and got 401 Unauthorized, having changed absolutely nothing.

Nothing is broken and nobody revoked anything. A token is a credential with a shelf life — issued for minutes or hours, and dead on schedule by design. The everyday version is a visitor's day pass at a building's front desk: it opens the same doors as an employee badge, and at six o'clock it stops working. Your pass expiring is the building working correctly. You collect a new one at the desk; you do not call security about a broken door.

Token issuedexpires_in: 3600

→

Works all hourevery request, 200

→

Sixty-first minute401 Unauthorized

→

Ask for a fresh tokenworks again

Keys Live Until Revoked, Tokens Die on Schedule

This, by the way, is the arrangement Chapter 1 hinted at: the server keeps no thread of your conversation, but it does remember issuing the credential — memory laid carefully on top of a stateless door.

Two credentials, two lifetimes. Vera's tnd_live_ key lives until somebody kills it: rotation, revocation, or the end of the partnership. Left alone it works next year. A token is issued with a stated lifetime — an hour is a common one — and stops being accepted the moment that lifetime is up, whether or not anyone touched it.

Plenty of APIs use both, and the pairing is the standard shape: your long-lived key proves who you are once, and what you get back is a short-lived token that does the day's work. The key is the thing you guard forever. The token is the thing you carry around, and if you drop it, it is worthless by dinnertime.

Why Expiry Is a Feature

Read the last page and this one becomes easy to like rather than resent. A stolen key is a stolen key until somebody notices. A stolen token is a stolen car that stops running at midnight — the thief has an hour, and after that the loot is a meaningless string.

Expiry shrinks the blast radius of every leak automatically, without anyone having to spot the leak first. It also cleans up after ordinary carelessness: the token pasted in a ticket last March, the one still sitting in an old note, the one in a screenshot on someone's desktop. All of them are inert. That is the trade the design makes — a small recurring inconvenience for you, in exchange for a permanently smaller window for everyone who might steal from you.

Reading the Signs

Three signals tell you that you are holding a token rather than a key. The first is the response that issued it: alongside the credential there is usually a field named expires_in, a number of seconds, and 3600 means one hour. The second is the documentation, which states the lifetime in plain words on the authentication page — Chapter 6 is about reading that page properly. The third is the symptom itself, and it has a shape worth memorizing.

The shape is: it worked, then it sat idle, then it stopped, and nothing changed in between. A credential that fails after a quiet stretch, having worked fine before the quiet stretch, has almost certainly expired rather than broken. The response body usually says so out loud too — an error message mentioning an expired credential rather than a missing one. Two different words, two different fixes.

What You Actually Do About It

At Vera's level, and probably at yours for a while, the whole practice is three things. Know which kind of credential you hold, because the documentation says. Expect the 401-after-idle pattern instead of being ambushed by it. And know where the instructions for getting a fresh one live, so the fix is a bookmark rather than an investigation.

What you do not have to do is manage the choreography by hand. Real tools that call APIs all day request new tokens automatically as the old ones expire, and the next page shows the same expiry idea inside a bigger ceremony. For now the practical upgrade is smaller and more valuable: when a credential fails after working, your first thought is the calendar, not the catastrophe.