Authentication and Authorization From a Design View

A consumer's first real interaction with an API is not the endpoint they actually want to call — it is authentication, and it happens before anything else about the API's design gets a chance to matter. A confusing authentication flow loses a developer before they ever see whether the resource modeling is elegant or the error messages are clear, because they gave up during setup and never got that far. This lesson is not a security course; it treats authentication and authorization as consumer-experience decisions with real, visible tradeoffs, the same way earlier lessons treated pagination or versioning as design decisions rather than pure implementation details.

Two different questions get conflated constantly and shouldn't be: authentication asks who is calling, and authorization asks what they're allowed to do. An API can get authentication right — a clean, well-documented way to prove identity — and still deliver a terrible consumer experience if authorization is coarse, undocumented, or surfaces as an opaque 403 with no indication of which specific permission was missing. Both halves are design surfaces a consumer experiences directly, not implementation details hidden behind the curtain.

The choices this lesson covers — which credential model to expose, how finely to scope permissions, how to fail when authorization is denied — shape a consumer's entire relationship with the API before their first successful business-logic call, and getting them wrong is rarely fixed with a documentation update; it usually requires a breaking migration every existing consumer has to go through.

Analogy🏏Cricket

🏏 Think of it like cricket: A stadium's accreditation system decides who gets through the gate at all — a valid, scanned credential for this specific match — before it ever asks the second, separate question of what that person is allowed to do once inside. A broadcast engineer's accreditation gets them past the gate and into the technical compound, but it does not, on its own, get them onto the players' balcony or into the team dressing room; a completely different, additional authorization is required for that, checked separately, even though the same person already proved who they were at the gate. A stadium that only ever checked the gate credential and let anyone past it wander anywhere would have solved identity and completely ignored permission, which is exactly the gap that leads to a broadcast engineer accidentally ending up somewhere they were never supposed to be. Just as the gate credential answers who this person is and a separate, later check answers what they're allowed to do once inside, authentication answers who is calling an API and authorization, checked separately, answers what that caller is allowed to do. Just as getting through the gate is only the first of two checks, not the whole system, a valid API credential is only the first of two checks a request has to clear. The insight is that identity and permission are genuinely separate questions, and a system that only answers one of them has only solved half the problem, no matter how well it solved that half.