API Keys

Two days after Vera sends the form, Jonas's reply lands. It is four lines long. One of them is her key: a single unbroken string that begins tnd_live_ and runs on for another forty characters of nonsense. Underneath it, one sentence of advice — treat this like a password — which is the entire next page and worth the wait.

An API key is a long random string the provider issues to you, which your requests carry so the server can tell that they are yours. It rides in a header on every single request, and one header is all that separates yesterday's refusal from today's data. The nearest everyday object is a hotel keycard: the front desk issued it, it opens your floor and not the roof, and they can kill it from the desk in seconds. The card is not the lock — it is a claim the lock checks.

What a Key Actually Is

Strip away the mystery and a key is a name tag the server can verify because the server printed it. Tandem generated that string, wrote it down next to Vera's account, and now recognizes it when it comes back. That is the whole mechanism. It is long and random for exactly one reason: so that nobody can guess it. Forty characters of randomness cannot be worked out by trying, the way a four-digit code can.

What a key is not is equally worth saying. It does no encrypting. It performs no cleverness in transit. It does not log you in to anything, because there is no session to be logged into — Chapter 1's point about servers remembering nothing between requests is about to collect its debt. The key identifies; HTTPS encrypts; those are two jobs done by two mechanisms, and you need both.

Where the Key Goes

The key travels in a request header called Authorization, the one Chapter 2 pointed at and left alone. Its value is two words: the scheme, then the credential. The scheme here is Bearer, which announces the kind of thing that follows — literally "whoever bears this". Then a space, then the key itself. In curl that is the -H flag from your six-flag toolkit, and it looks like -H "Authorization: Bearer tnd_live_...".

It goes on every request. Not the first one, not once per session — every one, forever. This is statelessness cashing in: the server keeps no memory of you between requests, so each request has to arrive self-contained, carrying its own proof of who sent it. Leave the header off one call in fifty and that one call gets a 401 entirely on its own.

Not every API uses this exact spelling. Some invent their own header name and want the raw key with no scheme word in front. A few, unhappily, accept the key as a query parameter in the URL. The documentation always states which, and it is always worth checking rather than assuming — and the next page explains why the query-parameter version is a habit to avoid even when an API offers it.

The Same Request, Twice

Here is the moment the chapter exists for, in two exchanges. First the request Vera sent yesterday: correct verb, correct address, no credential. The server reads it, cannot place her, and answers with the refusal and a short JSON body naming the reason. Note that the error is not cryptic — the response says in plain words what was missing.

curl -i https://api.tandem.example/v1/rides

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{"error": "unauthorized", "message": "No credentials provided"}

Now the same request with one header added. Nothing else changes — same tool, same verb, same path, same everything. The status line comes back 200 and the body carries actual rides, starting with rd_6b04, a trip on bike bk_0388 that ended at Old Market. The Thursday report's data source is officially open.

curl -i -H "Authorization: Bearer tnd_live_..." \
  https://api.tandem.example/v1/rides

HTTP/1.1 200 OK
Content-Type: application/json

{"data": [{"id": "rd_6b04", "bike_id": "bk_0388",
           "end_station_id": "st_014"}], "page": 1}

Keys Have Scopes, and Lives

Vera's key does not open everything Tandem has. It carries a scope — a named permission attached to the key, saying which parts of the API it may reach. Hers says stations:read rides:read — reading is everything the Thursday report needs. Writing — creating or cancelling reservations — is a separate scope she deliberately did not request. Ask for something outside your scope and you get the other refusal from the last page: 403, the one that means the server knows exactly who you are and is still declining.

A key also has a life, and it is not yours to keep. Tandem can revoke it in one click, issue Vera a replacement, or expire it on a date. That is the useful way to hold the idea: a key is a grant, not a possession. Someone lent it to you, under conditions, and can take it back — which is precisely what makes the next page's advice survivable rather than terrifying.