Invalidate the refresh token server-side for the authenticated user. Requires a valid JWT access token. Frontend removes both tokens from localStorage.

• The access token is validated via the Authorization: Bearer header.
• The refresh token is passed in the request body and is deleted from the database.
• After logout the user must log in again to obtain new tokens.
• If the refresh token is not found (already logged out), the server still returns 200 OK — the operation is idempotent from the user’s perspective.

sequenceDiagram
    actor User

    User->>+FE: clicks Logout

    FE->>+BE: POST /api/v1/auth/logout <br> Authorization: Bearer {accessToken} <br> LogoutRequest

    BE->>BE: validate JWT access token
    alt access token invalid or missing
        BE-->>FE: 401 Unauthorized <br> ErrorResponse
    end

    BE->>BE: validate request body
    alt request is invalid
        BE-->>FE: 400 Bad Request <br> ErrorResponse
    end

    BE->>DB: delete refresh token record (if exists)

    BE->>-FE: 204 No Content

    FE->>FE: remove accessToken and refreshToken from localStorage
    FE->>-User: redirect to login screen

POST /api/v1/auth/logout LogoutRequest:

{
  "refreshToken": "*****"
}

204 No Content (success, no body)

400 Bad Request (validation) ErrorResponse:

{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "errors": [
    { "field": "refreshToken", "message": "must not be blank" }
  ]
}

401 Unauthorized (missing or invalid access token) ErrorResponse:

{
  "status": 401,
  "code": "AUTHENTICATION_FAILED",
  "message": "Access token is missing or invalid"
}

Frontend

Validations

Backend

Validations

Test Cases