401 Unauthorized

Category: Status Codes & Responses

Description

Operations that require authentication should define a 401 Unauthorized response to indicate when authentication is missing or invalid.

What It Checks

This rule checks operations that have security requirements defined (either globally or at the operation level) and verifies they include a 401 response definition.

• Operations with global security requirements (defined at the root level)
• Operations with operation-level security requirements
• Checks for explicit 401 response definition in the responses object

Why It Matters

Documenting the 401 response is important for:

• API Consumer Clarity: Developers know which endpoints require authentication
• Error Handling: Clients can properly handle authentication failures
• Documentation Completeness: API documentation accurately reflects authentication requirements
• Contract Accuracy: The OpenAPI specification matches actual API behavior

Examples

Good

openapi: 3.0.0
security:
  - bearerAuth: []
paths:
  /users:
    get:
      operationId: getUsers
      responses:
        '200':
          description: List of users
        '401':
          description: Unauthorized - Authentication required

Bad

openapi: 3.0.0
security:
  - bearerAuth: []
paths:
  /users:
    get:
      operationId: getUsers
      responses:
        '200':
          description: List of users
        # Missing 401 response

Exceptions

• Operations that explicitly opt out of security with an empty security array
• Public endpoints that don't require authentication

Configuration

This rule has no configuration options. It is either enabled or disabled.

Related Rules

• Rule 57: Common Status Codes - Defines common error responses
• Rule 42: Consistent Errors - Error response consistency