Skip to content
API Design Learn/Auth & Versioning
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Authentication & Authorization Basics

5 min read

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.
401 vs. 403 - a genuinely different failure each time
# 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 Forbidden

Getting 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

The standard bearer-token authentication header
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.

Ready to Build This?

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.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!