HTTP 401 Unauthorized

What 401 means

Common causes

• The access token (often a JWT) has expired. Check its exp claim. Short-lived tokens without a refresh flow produce 401s after exactly N minutes.
• A malformed header: Authorization: <token> without the Bearer prefix, Bearer Bearer ..., surrounding quotes, or a trailing newline copied from an environment variable.
• Clock skew: nbf or iat is in the future for the server, or exp has passed on one machine but not another.
• Wrong audience or issuer: a staging token sent to production, or an OpenID Connect ID token sent where an access token is expected.
• CORS preflight: the browser's OPTIONS request never includes Authorization. If auth middleware runs before CORS handling, the preflight gets a 401 and the real request is never sent.
• Credentials dropped on a redirect: fetch() removes Authorization when following a redirect to a different origin, and curl -L won't send it to another host either. A redirect from api.example.com to www.api.example.com silently turns an authenticated call into a 401.
• Behind nginx, a custom auth header containing underscores (X_API_KEY) is dropped, because underscores_in_headers is off by default.

How to debug and fix a 401

curl -i https://api.example.com/me \
  -H "Authorization: Bearer $TOKEN"

HTTP/2 401
www-authenticate: Bearer error="invalid_token", error_description="The access token expired"

import cors from 'cors';

app.use(cors({ origin: 'https://app.example.com', credentials: true }));

app.use('/api', (req, res, next) => {
  const [scheme, token] = (req.get('Authorization') ?? '').split(' ');
  if (scheme !== 'Bearer' || !token) {
    res.set('WWW-Authenticate', 'Bearer realm="api"');
    return res.status(401).json({ error: 'missing_token' });
  }
  // verify the token, then:
  next();
});

async function apiFetch(url, options = {}) {
  const send = (token) =>
    fetch(url, {
      ...options,
      headers: { ...options.headers, Authorization: `Bearer ${token}` },
    });

  let res = await send(getAccessToken());
  if (res.status === 401) {
    res = await send(await refreshAccessToken());
  }
  return res;
}

Headers that matter with 401

WWW-Authenticate

Required in every 401. It names the scheme and, for bearer tokens, the reason (error="invalid_token").

Authorization

What the client sends: Authorization: Bearer <token> or Authorization: Basic <base64(user:pass)>.

Access-Control-Allow-Headers

For cross-origin calls, the preflight response must list Authorization, or the browser won't send it.

401 vs similar status codes

• 403 Forbidden: The server knows who you are and still says no. New credentials won't help.
• 407 Proxy Authentication Required: Like 401, but a proxy between you and the server wants credentials (Proxy-Authorization).
• 400 Bad Request: The request itself is malformed, regardless of credentials.

SEO impact of 401

Pages behind authentication return 401 (or redirect to a login page) to Googlebot, so they aren't indexed, which is usually what you want. Protecting a staging site with HTTP auth is more reliable than robots.txt; just remember to remove it at launch.

Related status codes

Looking for another code? Search the full HTTP status codes list, or read which code your API should return in the REST API status codes guide.

Learn more

Browse all developer guides →

Frequently Asked Questions