Why the API Wants to Know You

Vera has curl, she has the address, and she has the question her Thursday report actually needs: which rides ended where. So she sends GET /v1/rides the same way she sent everything in Chapter 3 — and gets back a status line instead of data. 401 Unauthorized. Her first reading is the natural one: the API is down, or she typed something wrong, or partners like her are not welcome after all.

All three are wrong. A 401 is not a fault and not a snub; it is a question. It means the request arrived, was understood, and carried no answer to who is asking. Think of a public library: anyone may walk in and read at the tables, but borrowing needs a card. The card is not there to keep you out. Lending at scale only works when the loans have names on them, and an API that hands out data at scale needs the same thing.

Do I know who is asking? No→401 Unauthorized

Known, but allowed this action? No→403 Forbidden

Known, and allowed. Yes to both→200 and your data

Who Is Asking?

Three ordinary business problems all reduce to the same requirement: a name on the envelope. The first is fair use. Tandem allows sixty requests a minute — Chapter 8 lives inside that number — and a limit of sixty per minute is meaningless unless the server can tell one caller from another. Anonymous traffic is one enormous nameless caller, and the only limit you can enforce on it is the one that hurts everybody.

The second is support. When Vera writes to Jonas because something returned an unexpected answer, his first move is to look up what her account actually sent. If her requests carried no identity, there is nothing to look up, and the most he can offer is sympathy. Identified requests are the reason "ask the provider" works at all.

The third is accountability, which is the polite word for consequences. Someone who hammers the API, scrapes it dry, or breaks the terms has to be stoppable without taking the service down for everyone else. With identity, Tandem revokes one credential. Without it, the only defense available is a wall in front of the whole door.

Authentication and Authorization

Authentication is proving who you are. Authorization is deciding what you are allowed to do. They arrive in the same conversation and get muddled constantly, partly because both start with the same four letters, auth — the field abbreviates them to authn and authz in writing just to keep them apart on the page.

The split is not academic; it is two different failures with two different fixes. A request with no credential fails the first question and gets 401: the server does not know you. A request with a perfectly valid credential that reaches for something outside its permissions fails the second and gets 403: the server knows exactly who you are and is still saying no. Chapter 7 meets that pair as errors to diagnose. You are meeting it here as an idea, which is the easier order.

The Tiers of Trust

APIs are not simply open or shut. There is a ladder, and each rung trades convenience for paperwork on purpose. At the bottom sit open endpoints: Tandem's station availability, readable by anyone, no credential at all — that is why every request in Chapter 3 worked. Above them sit partner endpoints, reached with a key issued to an organization, which is the next page and the one Vera needs. Above those sits delegated access, where an individual rider's own history is unlocked by the rider herself giving permission to an app, which is the last page of this chapter.

Read the ladder as a rule of thumb and it will hold for almost every API you meet: the more the data belongs to a specific person, the more ceremony stands between you and it. Public counts of bikes need nobody's consent. One rider's trip history needs that rider's.

What Tandem Asks of Partners

Vera's application is unremarkable, which is the point. A short form naming the organization and what she intends to do with the data, agreement to the API terms, and a named contact so there is a human on both ends of the relationship. Tandem reviews it, approves it, and issues a key. It takes two days.

This is Chapter 1's "an API is a product" seen from the queue rather than the boardroom. Products have customers, customers have accounts, and accounts have rules. The paperwork is not hostility toward Vera; it is the reason the counter is still open and still free for her to use.