Skip to content

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 Response
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

403Forbidden

VIP only! You might know who you are, but you're not on the guest list for this party.

HTTP Response
HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Access denied"}
πŸ”401Unauthorized
🚫403Forbidden

Authentication vs Authorization

401
Unauthorized
πŸ”

Authentication

Who are you?

The server doesn't know your identity. You need to prove who you are by providing valid credentials.

  1. User
  2. No credentials or invalid credentials
    401 Unauthorized
Common causes:
  • Missing authentication token
  • Expired login session
  • Invalid username/password
403
Forbidden
🚫

Authorization

What can you do?

The server knows who you are, but you don't have permission to access this resource.

  1. Authenticated User
  2. Valid credentials, but insufficient permissions
    403 Forbidden
Common causes:
  • Insufficient user role/permissions
  • Resource restricted to admins
  • IP address blocked

Quick Decision Guide

Use 401 when:
  • User hasn't logged in yet
  • Login credentials are missing or invalid
  • Authentication token is expired
  • Response should include WWW-Authenticate header
Use 403 when:
  • 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.

    401Unauthorized

    Correct response

    403Forbidden

    Don't use these

  • Expired JWT Token

    A user provides an authentication token that has expired or is invalid.

    401Unauthorized

    Correct response

    403Forbidden

    Don'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.

    403Forbidden

    Correct response

    401Unauthorized

    Don'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.

    403Forbidden

    Correct response

    401Unauthorized

    Don't use these

  • IP Address Blocked

    A request comes from an IP address that is explicitly blocked, regardless of authentication.

    403Forbidden

    Correct response

    401Unauthorized

    Don't use these

Description

The client must authenticate itself to get the requested response.

When to Use
  • No authentication credentials provided
  • Authentication token is invalid or expired
  • User needs to log in to access the resource
Common Causes
  • Missing authentication token
  • Expired login session
  • Invalid credentials
Description

The client does not have access rights to the content.

When to Use
  • User is authenticated but lacks required permissions
  • Resource is restricted regardless of authentication
  • IP address or region is blocked
Common Causes
  • Insufficient permissions
  • IP blocked
  • Resource restricted to certain users

Decision Tree

Does the request include authentication credentials?

Yes

Are the credentials valid?

Yes

Does the authenticated user have permission to access this resource?

Yes

Allow access (200 OK)

Status Code: 200

No

Use 403 Forbidden

Status Code: 403

No

Use 401 Unauthorized

Status Code: 401

No

Use 401 Unauthorized

Status Code: 401