Authentication & Authorization Basics
You'll learn to
- -Distinguish authentication (who are you) from authorization (what can you do), and know which status code fits which failure
- -Implement bearer token authentication and understand what a refresh token flow buys you
- -Trace what a well-behaved client does when an access token expires
- -Know when to answer 404 instead of 403, and why refresh tokens are rotated
Authentication and authorization are two different questions that get conflated constantly, including in status codes - and the distinction is exactly what a strong API design answer names explicitly instead of treating "auth" as one undifferentiated concept.
An Analogy: The Airport
At an airport you show your passport at the entrance to the secure area. If you have none, or it has expired, you are turned away, and the fix is to come back with a valid one. Later, at the gate for a particular flight, the agent scans your boarding pass. Your identity is already known, but the pass is not for this flight, so you are refused, and no amount of showing your passport again will change that.
- -The passport check is authentication: is this a known, valid identity? A failure is 401 Unauthorized, and trying again with fresh credentials can help.
- -The boarding pass at the gate is authorization: is this identity allowed to do this particular thing? A failure is 403 Forbidden, and re-authenticating cannot help.
Authentication vs. Authorization
- -Authentication ("who are you?"): verifying the caller's identity - a valid, unexpired credential. Failure here is 401 Unauthorized.
- -Authorization ("what can you do?"): given a known identity, deciding whether this specific action on this specific resource is allowed. Failure here is 403 Forbidden.
# No credential at all, or an expired/invalid one - identity unknown
GET /admin/reports
Authorization: Bearer expired-token-xyz
HTTP/1.1 401 Unauthorized
# Identity IS known (valid token), but this user isn't allowed to do this
GET /admin/reports
Authorization: Bearer valid-token-for-regular-user
HTTP/1.1 403 ForbiddenGetting this backwards (401 for a permissions failure, or 403 for a missing credential) genuinely confuses clients. A well-behaved client that sees 401 knows to try re-authenticating (refresh the token, prompt for login again). A client that sees 403 knows re-authenticating won't help, since the identity was fine and the problem is permissions. Swap the two and clients end up in unproductive retry loops.
A Third Answer: 404 to Hide That Something Exists
Sometimes even telling someone that a resource exists leaks information. If a user asks for /users/43/private-notes and 43 is somebody else, a 403 confirms that user 43 has notes. Many APIs return 404 Not Found for resources the caller is not allowed to see at all, so that forbidden and absent look identical. Use 403 when the caller knows the resource exists and should be told they lack permission, and 404 when its very existence is private.
Bearer Tokens and the Refresh Flow
POST /auth/login
{"email": "ada@example.com", "password": "..."}
HTTP/1.1 200 OK
{"access_token": "eyJhbGc...", "refresh_token": "8f3a...", "expires_in": 900}
# every subsequent authenticated request carries the access token:
GET /orders
Authorization: Bearer eyJhbGc...Access tokens are typically short-lived (minutes), which limits the damage window if one leaks - but re-logging in every 15 minutes would be unacceptable for users. A refresh token (longer-lived, used only against /auth/refresh to mint a new access token) solves this: the short-lived token limits exposure, and the longer-lived refresh token lets that exposure-limiting happen transparently to the user, without repeated logins.
Tracing a Token Expiry
- -At minute 0 the user logs in and receives an access token that lives 900 seconds (15 minutes) and a refresh token.
- -At minute 16 the client calls GET /orders with the access token, which has expired. The server answers 401.
- -The client does not show a login form. It sends the refresh token to POST /auth/refresh and receives a new access token and a new refresh token.
- -It repeats the original GET /orders once, which now succeeds. The user never noticed.
- -If the refresh itself fails with a 401, the refresh token is expired or revoked, and only now does the client send the user to log in.
Notice that the client retries the original request once, not in a loop. A loop on a request that fails for a permissions reason would never end. Notice also that the refresh token is replaced each time it is used. This is called rotation: the server remembers that the old refresh token is spent, so if an attacker uses a stolen copy after the real client has already used it, the server sees a spent token being presented, knows something is wrong, and can revoke the whole chain.
A refresh token should be usable only to mint new access tokens - never accepted directly as a substitute for one on ordinary API calls. Keeping that boundary strict limits what a leaked refresh token alone can actually do.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design The Gatekeeper in the API Design Lab's REST Foundations act.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!