HTTP 401 Unauthorized — What It Means & How to Debug

HTTP 401 Unauthorized indicates the request lacks valid authentication credentials — the client must provide a valid API key, token, or login to access the resource.

What It Means

The HTTP 401 Unauthorized status code means the client has not provided valid authentication credentials. The server understands the request but refuses to fulfill it until the client proves its identity. Despite the name “Unauthorized,” the correct interpretation is “unauthenticated” — the server doesn’t know who you are.

The response includes a WWW-Authenticate header that tells the client what authentication scheme to use (such as Bearer, Basic, or Digest). This header is what distinguishes 401 from 403 — a 401 response always includes WWW-Authenticate, while 403 does not.

When It’s Sent

• Missing API key — the request doesn’t include an Authorization header
• Invalid or expired token — the JWT token is malformed, expired, or revoked
• Wrong credentials — username/password combination is incorrect
• Missing login cookie — the user’s session cookie is absent or expired
• Unsupported auth scheme — the client sent a scheme the server doesn’t recognize

Real Example

curl -v https://api.example.com/admin/users

Expected response:

> GET /admin/users HTTP/1.1
> Host: api.example.com
>
< HTTP/1.1 401 Unauthorized
< WWW-Authenticate: Bearer realm="api.example.com"
< Content-Type: application/json
<
{"error":"Missing authentication token"}

The WWW-Authenticate header tells the client to use Bearer (token-based) authentication.

How to Debug

Browser DevTools

1. Open the Network tab
2. Trigger the request that returns 401
3. Click the request and check the Response tab for the error message
4. Look at the Request Headers — is Authorization present?
5. Check the Response Headers for WWW-Authenticate

curl

curl -v https://api.example.com/protected

If you see 401, add the authorization header:

curl -v -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/protected

Postman

In the Authorization tab, select the auth type (Bearer Token, Basic Auth, etc.) and enter the credentials. The status changes from 401 to 200 when the correct credentials are provided.

How to Fix

• Include the Authorization header — ensure Authorization: Bearer <token> or Authorization: Basic <base64> is present
• Check token expiration — JWTs have an exp claim — use jwt.io to decode and verify
• Verify the auth scheme — the server might expect Bearer but you sent Token
• Check the cookie — if using session-based auth, ensure the session cookie is sent and hasn’t expired
• API key location — some APIs expect the key in a header, others in a query parameter — check the docs

Common Causes

FAQ

Related Codes

• HTTP 200 OK — the response after providing valid credentials
• HTTP 403 Forbidden — authenticated but not permitted
• HTTP 400 Bad Request — general client error, often confused with 401
• HTTP 500 Internal Server Error — auth server is down or misconfigured