Error 401 not allowed is an HTTP status code that indicates that the client (usually a web browser) tried to access a web page or resource that requires authentication, but did not provide valid credentials. This error typically occurs when trying to access a website or web application that has restricted access and requires a login.
What causes a 401 error?
There are a few common reasons why a 401 unauthorized error might occur:
- The user is not logged in – Most 401 errors occur because the user is trying to access a page that requires logging in, but they have not logged in yet or their login session has expired.
- Invalid or missing credentials – If invalid username/password credentials are provided when trying to log in, a 401 error will be returned. Credentials could be missing if there is no Authorization header provided.
- Authentication method not supported – The resource being accessed may require a specific type of authentication that the client does not support. For example, accessing an API endpoint could require OAuth or basic auth.
- Authorization failure – Even if the user is logged in, they may not be authorized to access the particular resource they are requesting. Role-based access controls could reject their access.
- Cross-origin resource sharing (CORS) misconfiguration – APIs need to enable CORS to allow cross-origin requests. If it’s not enabled correctly, cross-origin requests may be unauthorized.
Common 401 error status messages
When a 401 error occurs, the server returns a status message that provides some additional context on what went wrong. Here are some common 401 status messages you may encounter:
- 401 Unauthorized – Generic status response when the request lacks valid authentication credentials.
- 401 Login required – User needs to login before accessing the requested resource.
- 401 Invalid credentials – Specified username, password, or auth token is invalid.
- 401 Session expired – User’s login session has ended and they need to login again.
- 401 Authentication failed – Authentication method failed, such as incorrect password.
- 401 Permission denied – User does not have necessary permissions to access the resource.
How to fix a 401 unauthorized error
Here are some steps you can take to resolve a 401 not authorized error:
- Log in or re-authenticate – If you haven’t logged in yet, authenticate with valid credentials for the website or API. If already logged in, your session may have expired so log in again.
- Provide proper credentials – If prompted for authentication, ensure you are providing a valid username and password or auth token.
- Request access – If you lack permissions, you may need to request elevated access to the resource you are trying to access.
- Check CORS settings – For APIs, validate the API allows cross-origin requests from your domain and enable CORS if needed.
- Clear cookies/cache – Clearing your browser cookies and cache can eliminate stale credential issues.
- Implement authentication – If building an API or website, properly implement user authentication and authorize requests.
401 error handling best practices
When designing applications and APIs, follow these best practices for handling 401 errors:
- Return custom error messages – Provide context on if login failed, invalid credentials, or permissions error.
- Use appropriate status codes – Distinguish between 401 Unauthorized and 403 Forbidden errors.
- Document authentication methods – Explain the required authentication and authorization mechanisms.
- Implement secure password storage – Safely hash and salt stored passwords on the server.
- Leverage refresh tokens – Use refresh tokens to obtain new access tokens when they expire.
- Set session length – Balance security and usability by setting appropriate session expiration length.
When to return a 401 error
A 401 error should be returned in these cases:
- No authentication provided – If an unauthenticated client tries to access a protected resource, return a generic 401 Unauthorized error.
- Invalid credentials – If the provided username/password or auth token is incorrect, return a 401 Invalid credentials error.
- Expired login session – If accessing a protected resource after the login session has expired, return a 401 Session expired error.
- Authorization failure – If the authenticated user lacks necessary permissions, send back a 401 Permission denied error.
401 vs 403 errors
The 401 Unauthorized and 403 Forbidden status codes are related but have slightly different meanings:
401 Unauthorized | 403 Forbidden |
---|---|
Returns when user is not authenticated | Returns when user is authenticated but not authorized |
Prompt for credentials | Don’t prompt for credentials |
Error is client-related | Error depends on server configuration |
So in summary, a 401 error indicates the client needs to provide credentials, while a 403 error means the client has sent credentials but those credentials do not have sufficient access privileges to the resource.
401 error code examples
Here are some examples demonstrating 401 error scenarios and how to handle them:
Example 1: Accessing protected API endpoint
If you try to access a protected API endpoint without an access token, it may return:
HTTP 401 Unauthorized { "error": "Unauthorized" }
To fix, obtain an OAuth 2.0 bearer token and provide it in the Authorization header:
GET /api/v1/users Authorization: Bearer jwt-token-123
Example 2: Logging into web app
When trying to log into a web app with invalid credentials it may return:
HTTP 401 Invalid credentials { "error": "Invalid username or password" }
To fix, provide the correct username and password when logging in.
Example 3: Accessing page after logout
If you try to access a protected page after logging out it may return:
HTTP 401 Session expired { "error": "Your session has ended. Please login again." }
Here you need to call the login endpoint again to start a new authenticated session.
Conclusion
Error 401 unauthorized indicates there is a problem with authentication when trying to access a protected resource. This is often caused by incorrect or missing credentials, an expired login session, or insufficient access privileges. To resolve a 401 error, re-authenticate with valid credentials, confirm you have permission, and implement proper authentication and authorization in your applications.