Password Reset

Overview

The password reset flow consists of two endpoints:

Forgot Password: Generate a reset token and send it via email
Reset Password: Use the token to set a new password

This two-step process ensures secure password recovery without exposing user credentials.

Forgot Password

POST /api/v1/auth/forgot-password

Generate a password reset token and send it to the user’s email address.

Request Body

string

required

User’s email addressValidation:

Must not be blank
Must be valid email format

Example: "[email protected]"

Response

Returns HTTP 200 regardless of whether the email exists in the database (security measure to prevent email enumeration).

Example Request

curl -X POST https://api.invernaderos.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Example Response

{
  "message": "If the email exists, a password reset link has been sent"
}

Status Codes

200

Request processed successfully. If the email exists in the database, a reset token has been sent.Note: This response is returned even if the email doesn’t exist, to prevent email enumeration attacks.

400

Bad Request

Validation error. Email field is missing or invalid format.

Email Flow

Validate Email

The API validates the email format using Jakarta Bean Validation

Generate Reset Token

If the user exists:

A unique reset token is generated (UUID format)
Token is stored in the database with expiration timestamp
Token expiration: 1 hour from generation

Send Email

An email is sent to the user containing:

Password reset link with embedded token
Token expiration time
Security warning about unsolicited requests

Return Response

API returns HTTP 200 without revealing whether the email exists

Security Note: The API always returns HTTP 200, even if the email doesn’t exist in the database. This prevents attackers from using this endpoint to enumerate registered email addresses.

Reset Password

POST /api/v1/auth/reset-password

Reset the user’s password using a valid reset token received via email.

Request Body

token

string

required

Reset token received via emailValidation: Must not be blankFormat: UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

newPassword

string

required

New password to set for the userValidation:

Must not be blank
Minimum length: 6 characters

Example: "newSecurePass123"

Response

Returns HTTP 200 on success, or HTTP 400 if the token is invalid or expired.

Example Request

curl -X POST https://api.invernaderos.com/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "newPassword": "newSecurePass123"
  }'

Example Response

{
  "message": "Password successfully reset. You can now log in with your new password."
}

Status Codes

200

Password successfully reset. The user can now log in with the new password.

400

Bad Request

Reset failed due to validation errors or invalid token.Common causes:

Token is invalid (doesn’t exist in database)
Token has expired (> 1 hour old)
Token has already been used
Password too short (< 6 characters)
Missing required fields

Reset Flow

Validate Token

The API checks if the token:

Exists in the database
Has not expired (< 1 hour old)
Has not been used previously

Hash New Password

The new password is securely hashed using BCrypt before storage

Update User

The user’s password is updated in the database and the reset token is marked as used

Invalidate Token

The reset token is deleted or marked as used to prevent reuse

Complete Password Reset Flow

Show End-to-End Flow Diagram

Token Generation and Storage

Show Token Database Schema

The reset token is stored in the user record:

ALTER TABLE metadata.users ADD COLUMN (
  reset_token VARCHAR(255),              -- UUID token
  reset_token_expiry TIMESTAMPTZ         -- Expiration timestamp (1 hour)
);

Token Generation Logic:

val token = UUID.randomUUID().toString()
val expiryTime = Instant.now().plus(1, ChronoUnit.HOURS)

user.resetToken = token
user.resetTokenExpiry = expiryTime
userRepository.save(user)

Token Validation Logic:

val user = userRepository.findByResetToken(token)
  ?: throw RuntimeException("Invalid token")

if (user.resetTokenExpiry.isBefore(Instant.now())) {
  throw RuntimeException("Token expired")
}

Email Template

Show Password Reset Email

Subject: Password Reset Request - Invernaderos API

Hello,

We received a request to reset your password for your Invernaderos account.

Click the link below to reset your password:
https://app.invernaderos.com/reset-password?token=a1b2c3d4-e5f6-7890-abcd-ef1234567890

This link will expire in 1 hour.

If you didn't request this password reset, please ignore this email or contact support
if you have concerns.

For security reasons, we will never ask you for your password via email.

---
Invernaderos Team

Security Considerations

Token Expiration: Reset tokens expire after 1 hour to limit attack window
Single Use: Tokens are invalidated after successful password reset
Email Enumeration Prevention: Always return HTTP 200 for forgot-password, regardless of email existence
Password Hashing: New passwords are hashed using BCrypt before storage
HTTPS Required: Password reset flow must use HTTPS in production
Rate Limiting: Consider implementing rate limiting to prevent abuse (not shown in examples)

Common Error Scenarios

Token Expired

Error: “Invalid or expired reset token”Cause: More than 1 hour has passed since the token was generatedSolution: Request a new password reset email via /forgot-password

Token Already Used

Error: “Invalid or expired reset token”Cause: The token was already used to reset the passwordSolution: If you need to reset your password again, request a new token via /forgot-password

Email Not Received

Possible Causes:

Email in spam/junk folder
Email address not registered in the system
Email service configuration issue

Solution: Check spam folder, verify email address, or contact support

Source Code References

Controller:
- Forgot Password: AuthController.kt:38-47
- Reset Password: AuthController.kt:49-56
Service:
- Forgot Password: AuthService.kt:70-74
- Reset Password: AuthService.kt:76-78
DTOs:
- ForgotPasswordRequest: AuthDTOs.kt:64-70
- ResetPasswordRequest: AuthDTOs.kt:72-81
User Service: UserService.kt:161-165 - Token generation logic
Email Service: EmailService.kt - Email sending implementation

Authentication

Tenant Management

Sensor Data

MQTT

Catalogs

Additional Endpoints

Overview

Forgot Password

POST /api/v1/auth/forgot-password

Request Body

Response

Example Request

Example Response

Status Codes

Email Flow

Reset Password

POST /api/v1/auth/reset-password

Request Body

Response

Example Request

Example Response

Status Codes

Reset Flow

Complete Password Reset Flow

Token Generation and Storage

Email Template

Security Considerations

Common Error Scenarios

Source Code References

Build docs developers (and LLMs) love

Authentication

Tenant Management

Sensor Data

MQTT

Catalogs

Additional Endpoints

​Overview

​Forgot Password

​POST /api/v1/auth/forgot-password

​Request Body

​Response

​Example Request

​Example Response

​Status Codes

​Email Flow

​Reset Password

​POST /api/v1/auth/reset-password

​Request Body

​Response

​Example Request

​Example Response

​Status Codes

​Reset Flow

​Complete Password Reset Flow

​Token Generation and Storage

​Email Template

​Security Considerations

​Common Error Scenarios

​Source Code References

Build docs developers (and LLMs) love

Overview

Forgot Password

POST /api/v1/auth/forgot-password

Request Body

Response

Example Request

Example Response

Status Codes

Email Flow

Reset Password

POST /api/v1/auth/reset-password

Request Body

Response

Example Request

Example Response

Status Codes

Reset Flow

Complete Password Reset Flow

Token Generation and Storage

Email Template

Security Considerations

Common Error Scenarios

Source Code References