The API Key Is a Password

There is one part of Milo's request Tessa has not asked about. It does not sit in the body with the messages; it rides alongside them, and it is a long, meaningless-looking run of letters and digits that goes out with every single call.

That is the API key — the credential that tells the provider whose account is asking and, just as importantly, whom to bill. Waymark was issued one when its account was opened. As far as the provider's servers are concerned, that string is not a way of proving who Waymark is. It is Waymark.

Chapter 6 drew the rule about credentials in the abstract and promised that this chapter would give it a face. Here is the face: a password that spends money.

What the Key Does

Two jobs, in one string. The first is access: the provider will not answer a request that arrives without a valid key. Send one without, or with a key that has been cancelled, and back comes the 401 from the last page but one — "you are not on the list". Tessa now knows exactly what the list is.

The second job is billing. Every request carrying Waymark's key is counted against Waymark's account, and the tokens it uses land on Waymark's invoice. There is no separate step where somebody approves the spending. The key arrives, the work happens, the meter turns.

Which means the key is not really a login in the ordinary sense. When Tessa signs into her email, a password gets her to an interface where she can then do things. A key skips all of that: it is presented and the work begins, thousands of times an hour if that is how fast the requests come. There is no session, no screen, no moment where somebody might notice something is off.

Why It Is Exactly a Password

Anyone holding the string can make requests billed to Waymark. That is the whole security model, and it is worth saying in the bluntest available words: the server cannot tell Tessa from a stranger who copied Tessa's key. Both send the same characters. Both get served.

So a leaked key is not an embarrassment to be tidied up later. It is somebody else's questions on Waymark's invoice, running at machine speed, until it is stopped. Keys that end up somewhere public are found quickly — there are people who do nothing but look for them — and the finding is automated, which means the gap between "posted by accident" and "being used" is measured in minutes rather than weeks.

The nearest everyday thing is a company charge card number. Not the physical card — the digits. Whoever has the digits can spend on the account, the shop has no way to tell whether the person reading them out is entitled to, and the statement arrives at the end of the month either way. Nobody reads those digits aloud in a room they do not control, and nobody waits to be certain before cancelling one they might have exposed.

Handling Rules, Concrete

Four rules, and they are short because they are absolute.

A key never goes in a chat box. This is Chapter 6's rule arriving exactly where it was aimed: paste a key into a chat and it lands in a conversation history, on a company's servers, under a retention policy Waymark does not set — and a secret that has travelled is no longer a secret. The moment it happens most often is the helpful one: pasting an error message that happens to contain the key, to ask what went wrong. Strip it first.

A key never goes in email, in a shared document, in a message to a colleague, or in a screenshot. Each of those makes copies that outlive the reason they were made.

A key lives in the place the tool provides for keeping keys. Every serious product has one — a store meant for exactly this, separate from the code and from the documents. Setting that up is Milo's job, not this book's, and not Tessa's. Knowing that it exists and asking whether it was used is very much hers.

And if a key might have leaked, it is cancelled and replaced immediately. The word is revoke: telling the provider that this string is no longer valid, so that any request carrying it is refused from that second on. Revoking is deliberately cheap. Issue a new key, put it where the old one lived, and the work resumes in minutes.

Revoke first, investigate afterwards. The instinct to establish whether the key really was exposed before doing anything drastic gets this exactly backwards, because the investigation takes an hour and the abuse takes four minutes. There is no version of this where waiting is the careful choice.

One Key, One Purpose

The last habit costs nothing and pays twice. Issue a separate key for each distinct use: one for the review-classification script, one for whatever the website does, one for Milo's experiments while he is building something.

The first payoff is containment. If the experiment key ends up in the wrong place, that one key is revoked and the review script never notices. One shared key across everything means one leak stops everything at once, on a Tuesday, with no warning.

The second payoff is legibility, and it arrives on the last page of this chapter. When each use has its own key, the provider's usage breakdown reports spending per key — which means the invoice arrives already itemized by what the money was for. That is the difference between a bill Tessa can explain to her manager and a single number she can only pay. Departments get their own cards for the same reason.