6 lessons

API Security Boundary

Where authentication and authorization live in the contract: token placement, resource-level permission design, scopes, API keys, rate limits and quotas as documented behavior.

Requirement→Consumers→Resource Model→Style→Contract→Validation→Authorization→Errors→Idempotency→Pagination→Versioning→Observability→Evolution→Trade-offs

Every lesson below names the consumers, the design question and the guarantee before recommending anything. Recommendations come with what they cost, when not to use them, and how they evolve.

Authentication in the Contract

The contract does not implement authentication — it states which credential each consumer type presents, where it rides, how long it lives, and exactly what a 401 means. The mechanisms are Security Engineering's domain; the promises are yours.

Q · Which credential does each consumer of this API present, where does it go in the request, and what is the documented behavior when it is missing, expired or wrong?
Authorization Design in the Contract

Every operation needs a documented answer to "who may call this?" — and the enforcement must check the *object*, not just the endpoint. Missing object-level checks are the most exploited API flaw in the wild, and the contract decides whether denial reads as 403 or 404.

Q · For every operation and every resource id in it: who is allowed, how does a consumer discover that from the docs, and what exactly happens when the answer is no?
Scopes: Least Privilege as Contract Surface

A scope caps what a credential may ask for — `projects:read` cannot touch billing even if the user behind it can. Too coarse and every integration holds admin; too fine and nobody can predict which scope an endpoint needs. The catalog is the contract.

Q · How does the contract let a consumer request exactly the access its integration needs — and no more — in units both the consumer and the resource owner can understand?
API Keys: Identity for Applications

An API key identifies an application — which makes it the natural unit for scoping, rate limiting and metering, and the wrong tool the moment a user is delegating access. Keys are credentials: prefixed, hashed at rest, scoped, and rotatable without downtime.

Q · What does an API key actually identify, what lifecycle must the contract support for it, and when is a key the wrong credential entirely?
The Rate-Limit Contract

Every API has a rate limit — the only question is whether it is a documented 429 with headers or an undocumented collapse. The contract names the dimensions (per key, per user, per endpoint class), the numbers, and exactly how a well-behaved client should respond.

Q · What does a client that hits the limit actually experience — and does the contract give it enough information to slow down correctly instead of retrying itself into a ban?
Quotas vs Rate Limits

A rate limit protects the platform second by second; a quota is an entitlement over a billing period. 100 requests/second and 1M requests/month are different promises with different rejections, resets and communication duties — conflating them breaks both.

Q · Is the caller being slowed because the platform needs protecting right now, or stopped because they have consumed what their plan entitles them to — and does the contract distinguish the two?