401 vs 403
Unauthorized vs Forbidden
401Unauthorized
Who are you?! The bouncer needs to see some ID before letting you in. Time to log in!
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer403Forbidden
VIP only! You might know who you are, but you're not on the guest list for this party.
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error": "Access denied"}Authentication vs Authorization
Authentication
Who are you?
The server doesn't know your identity. You need to prove who you are by providing valid credentials.
- User
- No credentials or invalid credentials401 Unauthorized
- Missing authentication token
- Expired login session
- Invalid username/password
Authorization
What can you do?
The server knows who you are, but you don't have permission to access this resource.
- Authenticated User
- Valid credentials, but insufficient permissions403 Forbidden
- Insufficient user role/permissions
- Resource restricted to admins
- IP address blocked
Quick Decision Guide
- User hasn't logged in yet
- Login credentials are missing or invalid
- Authentication token is expired
- Response should include
WWW-Authenticateheader
- User is logged in and identified
- User lacks necessary permissions/role
- Resource is restricted to specific users
- Re-authenticating won't help access the resource
Key Insight
401 is about identity (Who are you?), while 403 is about permissions (What can you do?). If the user could fix the issue by logging in with different credentials, use 401. If even an admin account couldn't access it, use 403.
Real-World Scenarios
When should you use each status code? Here are practical examples to help you decide.
Missing Authentication Token
A user tries to access /api/profile without providing a JWT token or session cookie.
401UnauthorizedCorrect response
403ForbiddenDon't use these
Expired JWT Token
A user provides an authentication token that has expired or is invalid.
401UnauthorizedCorrect response
403ForbiddenDon't use these
Authenticated User, Wrong Role
A logged-in regular user tries to access /admin/settings. They're authenticated, but they don't have admin privileges.
403ForbiddenCorrect response
401UnauthorizedDon't use these
API Key with Insufficient Permissions
A developer uses a valid API key, but it only has read permissions and they're trying to write data.
403ForbiddenCorrect response
401UnauthorizedDon't use these
IP Address Blocked
A request comes from an IP address that is explicitly blocked, regardless of authentication.
403ForbiddenCorrect response
401UnauthorizedDon't use these
The client must authenticate itself to get the requested response.
- No authentication credentials provided
- Authentication token is invalid or expired
- User needs to log in to access the resource
- Missing authentication token
- Expired login session
- Invalid credentials
The client does not have access rights to the content.
- User is authenticated but lacks required permissions
- Resource is restricted regardless of authentication
- IP address or region is blocked
- Insufficient permissions
- IP blocked
- Resource restricted to certain users
Decision Tree
Does the request include authentication credentials?
Are the credentials valid?
Does the authenticated user have permission to access this resource?
Allow access (200 OK)
Status Code: 200
Use 403 Forbidden
Status Code: 403
Use 401 Unauthorized
Status Code: 401
Use 401 Unauthorized
Status Code: 401