Back to list
401

Unauthorized

4xx Client Error

.md

ELI5

You need to prove who you are before you can access this. Please log in or provide valid credentials.

Server perspective

Use 401 when authentication is missing, invalid, or expired and the client can authenticate.

When to use

  • •Return 401 when credentials are absent or cannot be verified
  • •Use it for expired tokens when refreshing or signing in can resolve the request
  • •Missing authentication token or API key
  • •Expired authentication credentials
  • •Invalid login credentials
  • •Malformed authorization headers
  • •First-time access requiring authentication

How to respond

  • •Include a WWW-Authenticate header with at least one authentication challenge (RFC 9110 requires this)
  • •Keep error details concise so credentials are not leaked

Headers to consider

  • •WWW-Authenticate

Response body

  • •Optionally include a machine-readable auth error such as token_expired

Server-side pitfalls

  • •Use 403 when the user is authenticated but still not allowed
  • •Avoid revealing whether a sensitive account or resource exists
  • •User is authenticated but lacks permission (use 403 Forbidden)
  • •Resource doesn't exist (use 404 Not Found)
  • •Request format is wrong (use 400 Bad Request)

Examples

Missing API key

Request:GET https://api.example.test/api/users
Response:401 Unauthorized # Headers WWW-Authenticate: Bearer realm="api" Content-Type: application/json # Body { "error": "unauthorized" }

API requires authentication but no credentials provided

Expired JWT token

Request:GET https://api.example.test/api/profile # Headers Authorization: Bearer <expired-jwt>
Response:401 Unauthorized # Headers WWW-Authenticate: Bearer realm="api" Content-Type: application/json # Body { "error": "unauthorized" }

Token was valid once but has now expired

References

Related Status Codes

403

Forbidden

I know who you are, but you're not allowed to do this. You don't have permission for this action.