SYSTEMCLINIC AUTHENTICATION API SPECIFICATION (FOR AI CONSUMPTION)

[CONTEXT] This document specifies the backend authentication API for SystemClinic. It is designed to be read by AI agents to generate, debug, or maintain client-side authentication logic. It focuses strictly on API contracts, schemas, and behavior. All frontend framework-specific details are ignored.

[GLOBAL RULES]

1. BASE URL PATH: /auth
2. CONTENT-TYPE: application/json (both request and response)
3. PROTECTED ROUTES: Require HTTP header Authorization: Bearer <accessToken>
4. ERROR RESPONSES: Standard JSON error payloads with property message.

---

[ENDPOINT SPECIFICATIONS]

1. Register User

• Method: POST
• Route: /auth/register
• Description: Registers a new user. On success, automatically performs login and returns a valid session.
• Request Schema:

  type RegisterRequest = {
    email: string;           // Required, Max: 150, Valid email format
    password: string;        // Required, Min: 8, Max: 100
    confirmPassword: string; // Required, Must match password
    firstName: string;       // Required, Min: 2, Max: 100, pattern: ^[a-zA-ZÀ-ÿ\s'\-]+$
    lastName: string;        // Required, Min: 2, Max: 100, pattern: ^[a-zA-ZÀ-ÿ\s'\-]+$
  }

• Response (201 Created):

  type AuthResponseDto = {
    accessToken: string;
    refreshToken: string;
    expiresAt: string; // ISO 8601 UTC DateTime string (ex: "2026-05-25T17:30:00Z")
    user: UserDto;
  }
  type UserDto = {
    id: string;
    email: string;
    firstName: string;
    lastName: string;
    roles: string[];
    companyId: string | null;
  }

• Errors:
  • 400 Bad Request: Validation failures (e.g. non-matching password, invalid name pattern) or email already registered.
    • Example message: "O Email informado já está em uso."

2. Login User

• Method: POST
• Route: /auth/login
• Description: Authenticates user using email and password.
• Request Schema:

  type LoginRequest = {
    email: string;    // Required, Valid email format, Max: 150
    password: string; // Required, Max: 100
  }

• Response (200 OK):

  type AuthResponseDto = {
    accessToken: string;
    refreshToken: string;
    expiresAt: string;
    user: UserDto;
  }

• Errors:
  • 401 Unauthorized: Invalid credentials or locked-out account.
    • Example invalid credentials: "Invalid email or password."
    • Example account lockout: "Account is locked. Please try again later."

3. Refresh Token Rotation

• Method: POST
• Route: /auth/refresh
• Description: Exchanges an existing refresh token for a new set of tokens (access + refresh). Uses rotation: the submitted refresh token is immediately marked as revoked, and a brand new refresh token is returned.
• Request Schema:

  type RefreshTokenRequest = {
    refreshToken: string; // Required, Max: 512
  }

• Response (200 OK):

  type AuthResponseDto = {
    accessToken: string;
    refreshToken: string;
    expiresAt: string;
    user: UserDto;
  }

• Errors:
  • 401 Unauthorized: Submitted refresh token is invalid, expired, or already revoked/used.
    • Example message: "Refresh token is expired or revoked."

4. Forgot Password

• Method: POST
• Route: /auth/forgot-password
• Description: Triggers password reset process. Sends an email containing a link with query parameters: email and token.
• Request Schema:

  type ForgotPasswordRequest = {
    email: string; // Required, Valid email format, Max: 150
  }

• Response (200 OK):

  type ForgotPasswordResponse = {
    message: string; // "Se o endereço de e-mail estiver registrado, um link de redefinição foi enviado."
  }

• Behavior Note: Returns 200 OK with success message even if the email does not exist to prevent account enumeration.

5. Reset Password

• Method: POST
• Route: /auth/reset-password
• Description: Resets password using the token received by email. Under the hood, this action revokes all active refresh tokens for the user.
• Request Schema:

  type ResetPasswordRequest = {
    email: string;              // Required, Valid email format, Max: 150
    token: string;              // Required, Max: 2048, ASP.NET Identity reset token
    newPassword: string;        // Required, Min: 8, Max: 100, pattern: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z\d]).{8,100}$
    confirmNewPassword: string; // Required, Must match newPassword
  }

• Response (200 OK):

  type ResetPasswordResponse = {
    message: string; // "Password reset successfully."
  }

• Errors:
  • 400 Bad Request: Validation failures, weak password, or invalid/expired token.

6. Get Current User Profile (Me)

• Method: GET
• Route: /auth/me
• Description: Retrieves the profile data of the currently logged-in user matching the access token.
• Headers: Authorization: Bearer <accessToken>
• Response (200 OK):

  type UserDto = {
    id: string;
    email: string;
    firstName: string;
    lastName: string;
    roles: string[];
    companyId: string | null;
  }

• Errors:
  • 401 Unauthorized: Missing, invalid, or expired Bearer token.

7. Validate Access Token

• Method: POST
• Route: /auth/validate-token
• Description: Cryptographically validates whether an access token is structurally valid.
• Request Schema:

  type ValidateTokenRequest = {
    token: string; // Required, Max: 2048
  }

• Response (200 OK):

  type ValidateTokenResponse = {
    isValid: boolean;
  }

---

[CLIENT AUTH FLOW IMPLEMENTATION SPECIFICATION]

An AI building or maintaining the client authentication module should adhere to the following sequence:

1. Storage:
   • Keep the volatile accessToken and the user profile info in memory.
   • Keep the refreshToken in a secure client storage mechanism (e.g. secure local storage) to persist the session across page reloads.
2. Request Decoration:
   • Set up an interceptor/middleware in the HTTP client to inject the header Authorization: Bearer <accessToken> if accessToken is present in memory.
3. Token Rotation (401 Interceptor):
   • When any protected API request fails with a 401 Unauthorized status:
     1. Pause/queue all incoming requests.
     2. Call POST /auth/refresh sending the saved refreshToken.
     3. If POST /auth/refresh returns 200 OK containing a new accessToken and refreshToken:
        • Update memory with the new accessToken.
        • Save the new refreshToken to local storage.
        • Replay the original failed request and any queued requests using the new accessToken.
     4. If POST /auth/refresh returns 401 Unauthorized:
        • Clear memory (accessToken, user details).
        • Delete the stored refreshToken.
        • Redirect user to the login screen.
4. Simultaneous Request Handling:
   • If multiple requests fail with 401 at the same time, the HTTP client must only trigger one /auth/refresh request. The rest must be queued and processed only after the single refresh succeeds or fails.
5. Password Reset Invalidation:
   • Note that executing a successful /auth/reset-password automatically invalidates all refresh tokens for that user on the backend.