401 Unauthorized

Client Error

The request lacks valid authentication credentials for the target resource. 401 indicates the server does not know who you are. The credentials are missing, malformed, or have expired. The response must include a WWW-Authenticate header describing the authentication scheme(s) the server expects, although in practice many APIs omit it. Despite the name, 401 has nothing to do with authorization in the access-control sense; it is purely about authentication. Use 403 when the identity is known but lacks permission.

When does this happen?

Return 401 when the server cannot identify the caller. The Authorization header is missing entirely, the bearer token is malformed, the API key is unknown, the session cookie has expired, or the JWT signature failed verification. Browsers respond to 401 by triggering the native HTTP authentication prompt only when the response includes a WWW-Authenticate: Basic or WWW-Authenticate: Digest header. Modern APIs almost always avoid that header to suppress the prompt. For cookie-based sessions, the convention is that the client should redirect to a login page on receiving 401. The response can include details about why authentication failed ("token expired" vs "signature invalid" vs "key revoked") but should not leak whether a specific username exists, which would help account enumeration attacks. 401 is also the right answer when a token has expired and the client should refresh it. Exposing this distinction through the response body lets SDKs trigger token refresh automatically.

Common causes

• Authorization header missing on a protected endpoint. The server cannot identify the caller.
• Bearer token expired and the client did not refresh it before retrying.
• JWT signature verification failed. The token was tampered with or signed with the wrong key.
• API key revoked, rotated, or never existed in the database.
• Session cookie expired or invalidated server-side after logout.
• Authorization header malformed. E.g. "Bearer" missing, or "Basic" with non-base64 content.
• Clock skew between client and server causing JWT exp claim to look stale even though the token is still valid.
• Request hit the wrong tenant. The credential is valid for tenant A but the URL is in tenant B's namespace.

How to fix it

• Include a valid Authorization header. Bearer <token> for OAuth/JWT, Basic <base64> for HTTP basic, or whatever scheme your API documents.
• Refresh expired tokens via your OAuth refresh-token flow before retrying the original request.
• Verify the API key is correct, active, and scoped to the resource you are accessing. Many APIs have separate keys for staging and production.
• Check WWW-Authenticate in the response. It tells you which scheme the server wants (Bearer, Basic, Digest, custom).
• Synchronize the client clock with NTP. JWT exp claims fail with even small skew.
• If the 401 came from a CDN or edge layer, check whether your origin is sending credentials through correctly. Some configurations strip Authorization at the edge.
• When refreshing fails, force the user back through the login flow rather than retrying indefinitely.

Real-world examples

Client calls GET /v1/me without an Authorization header.

Server returns 401 with WWW-Authenticate: Bearer and body {"error":"missing credentials"}. SDK prompts user to log in.

Access token expired one minute ago and the client did not refresh before retrying.

Server returns 401 with {"error":"token_expired"}. Client uses its refresh token to obtain a new access token and retries the original request transparently.

User logs out in one tab and an open API call in another tab uses the now-invalid session cookie.

Server returns 401. Frontend catches it and redirects the user to /login.

Developer copies an API key from a screenshot but the trailing equals sign is missing.

Server returns 401 because the key does not match anything in the database. Developer regenerates and copies the full key.

JWT was signed with an old key after a rotation.

Server returns 401 with signature_invalid in the error body. The client must obtain a fresh token signed with the current key.

Debugging

• Run curl -v -H 'Authorization: Bearer <token>' https://api.example.com/v1/me and inspect the response body. Most APIs report the specific failure reason.
• Decode the JWT at jwt-debugger-style tools to inspect exp, iat, and aud claims. Expiry and audience mismatches are the top two failure modes.
• Check the WWW-Authenticate response header. It tells you exactly which scheme the server expects.
• Verify the system clock with date. A clock that drifts by even 30 seconds will fail strict JWT validation.
• If using OAuth, capture the full refresh flow with curl -v and confirm the refresh endpoint returns a new access token and the retry uses it.

How it differs from related codes

HTTP 403

401 means we do not know who you are. 403 means we know who you are but you are not allowed to do this. Re-authenticating fixes 401; it will not fix 403.

HTTP 407

407 is identical to 401 in semantics but applies to authentication against a proxy rather than the origin server. The header used is Proxy-Authenticate instead of WWW-Authenticate.

HTTP 404

Some APIs return 404 instead of 401/403 for protected resources to avoid leaking existence. Conceptually 401 says "not authenticated" while 404 says "no such resource". Security trade-off, not interchangeable.

Related status codes

400 403 405 422 429