What it means
Not authenticated - we do not know who you are. Misnamed in the spec: it means unauthenticated. Must include WWW-Authenticate. If we know who you are and you still may not do this, that is 403.
- Class
- 4xx Client error
- Defined in
- RFC 9110 §15.5.2
- Cached by default
- No
When you receive a 401
- As far as the server can tell you are not signed in: the token is missing, expired, malformed or issued for another audience.
- Check the
Authorizationheader is actually sent. Cross-origin redirects drop it, and a CORS setup that does not allow it will too. - An expired access token usually means refresh it and retry once. A second 401 means sign in again.
When you send a 401
- When there are no credentials, or the ones sent are invalid or expired.
- Include
WWW-Authenticate, for exampleBearer error="invalid_token", so the client knows what failed. - If you know who the caller is and they are simply not allowed, that is
403.
On the wire
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired"