Unauthorized

Overview

401 Unauthorized means authentication is required and the request was rejected because credentials are missing or invalid. Despite the name "Unauthorized," it really means "unauthenticated" — the server could not verify who is making the request.

By spec a 401 response should include a WWW-Authenticate header stating which auth scheme to use. It implies access may be possible after re-authenticating with valid credentials, which distinguishes it from 403 where re-authenticating will not help.

When it happens

• It is returned when the Authorization header is absent, or the token is invalid because it expired or was tampered with.
• It occurs when the API key, username, or password is wrong, or the token's audience/scope does not match.

Request / Response example

GET /api/me HTTP/1.1
Host: api.example.com
Authorization: Bearer expired.token.here

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"
Content-Type: application/json

{"error":"invalid_token","message":"Access token has expired"}

In code

app.use('/api', (req, res, next) => {
  const token = req.headers.authorization;
  if (!isValid(token))
    return res.status(401).set('WWW-Authenticate', 'Bearer').json({ error: 'invalid_token' });
  next();
});

curl -i https://api.example.com/api/me
# -> 401 Unauthorized  (add: -H 'Authorization: Bearer <token>')

Notes

• The key difference: 401 means "we don't know who you are" (authentication), 403 means "we know but you lack permission" (authorization).
• In browser Basic auth, receiving a 401 pops up a login prompt — that is driven by the WWW-Authenticate header.
• Some frameworks/CDNs express session expiry with non-standard codes like 419, but the standard is 401.

Related status codes

Related headers

Specification