HTTP Status Codes

401 Unauthorized

Authentication is required and either missing or invalid. Despite the name, it is about authentication — proving who you are — not permissions.

What it means

401 Unauthorized means the request was not authenticated. The response must include a WWW-Authenticate header describing how to authenticate. Once the client supplies valid credentials, the same request should succeed.

HTTP RESPONSE
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

401 vs 403

Authentication vs authorization

401 means 'I don't know who you are — authenticate.' 403 means 'I know who you are, and you may not do this.' Sending 401 when credentials were valid but insufficient is a common mix-up.

Why it matters

  • It drives the browser and API auth flow via WWW-Authenticate, prompting for credentials or token refresh.
  • Correctly distinguishing 401 from 403 keeps client retry logic sane.

Common mistakes

  • Omitting the WWW-Authenticate header, which the spec requires on a 401.
  • Using 401 when the user is authenticated but lacks permission (that is 403).

How WebInspect checks this

  • The API Inspector reports auth-related headers and whether a protected endpoint challenges correctly with 401.