Unauthorized

ⓘ Quick Definition

The request requires user authentication. The client must authenticate itself to get the requested response. Despite the name "Unauthorized," this status code is actually about authentication, not authorization. It means the server does not know who you are. You need to provide valid credentials (such as a username/password, API key, or token) before the server will process your request.

⏰ When It Occurs

A 401 error occurs when you attempt to access a protected resource without providing valid authentication credentials. This is extremely common in API development, where every request must include a token or API key. It also happens when logging into websites with incorrect credentials, or when a session or token has expired.

The server typically responds with a WWW-Authenticate header indicating the authentication scheme expected (e.g., Basic, Bearer, Digest).

⚠ Common Causes

• Missing Authorization header - The request doesn't include any authentication credentials
• Expired JWT/session token - The token was valid but has passed its expiration time
• Invalid API key - The API key is incorrect, revoked, or belongs to a different environment
• Incorrect username/password - The credentials provided do not match any account
• Token not included in request - The login was successful but the token isn't being sent with subsequent requests
• OAuth token revoked - The user or admin revoked the OAuth access token
• CORS blocking credentials - Cross-origin requests not configured to include credentials

Platform-Specific Notes:

Nginx Returns 401 when auth_basic or auth_request modules reject the credentials. Check your auth configuration block.

Apache Triggers 401 with mod_auth_basic or mod_auth_digest when credentials fail validation against .htpasswd.

Cloudflare May return 401 when Access policies require authentication, or when API tokens used with Cloudflare API are invalid.

Node.js Express middleware like Passport.js or custom JWT verification returns 401 when token validation fails.

🛠 How to Fix

1. Include valid credentials in request - Add an Authorization header with your token, API key, or username/password
2. Check if token has expired - Decode your JWT to verify the exp claim, or check session expiry time
3. Verify API key is correct - Confirm you're using the right key for the right environment (dev vs. production)
4. Ensure Authorization header format is correct - Use the proper scheme: Bearer <token>, Basic <base64>, etc.
5. Check CORS configuration for credentials - Set credentials: 'include' in fetch and Access-Control-Allow-Credentials: true on server
6. Refresh expired tokens - Use your refresh token to obtain a new access token from the auth endpoint
7. Verify authentication endpoint - Make sure the login/auth URL is correct and the service is running

💻 HTTP Example

# Request without authentication
GET /api/user/profile HTTP/1.1
Host: api.example.com
# Missing: Authorization header

# Server Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

{
  "error": "Unauthorized",
  "message": "Authentication token is required",
  "statusCode": 401
}

# Correct request with Bearer token
GET /api/user/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

🔗 Related Status Codes