Authentication

Overview

Kin Conecta uses a combination of Spring Security and BCrypt password encoding for user authentication. The current implementation provides basic authentication with endpoints for user login and registration.

The authentication system is currently configured to permit all requests for development. Implement proper JWT or session-based authentication before production deployment.

Security Configuration

The API is configured with Spring Security using the following settings:

Password Encoding

Passwords are hashed using BCrypt algorithm with automatic salt generation:

public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

CSRF Protection

CSRF protection is currently disabled for API endpoints:

httpSecurity.csrf(csrf -> csrf.disable())

CSRF protection is disabled. If implementing session-based authentication, enable CSRF protection for security.

Request Authorization

All endpoints currently permit unrestricted access:

httpSecurity.authorizeHttpRequests(
    auth -> auth
        .requestMatchers("/api/**").permitAll()
        .anyRequest().permitAll()
)

User Model

The User entity contains the following authentication-related fields:

Long

required

Unique user identifier (auto-generated)

String

required

User’s email address (unique)

password

String

required

BCrypt hashed password

role

UserRole

required

User role: TOURIST, GUIDE, or ADMIN

accountStatus

AccountStatus

required

Account status: ACTIVE, SUSPENDED, PENDING_VERIFICATION, or DEACTIVATED

fullName

String

required

User’s full name

phoneE164

String

required

Phone number in E.164 format

emailVerifiedAt

Date

Timestamp of email verification

Timestamp of last successful login

createdAt

Date

required

Account creation timestamp

updatedAt

Date

required

Last account update timestamp

Authentication Endpoints

Authenticate a user with email and password.

curl -X POST http://localhost:8080/kinconecta/api/user/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Endpoint: POST /kinconecta/api/user/login Request Body:

string

required

User’s email address

password

string

required

User’s password (will be validated against BCrypt hash)

Response: Returns a boolean indicating authentication success:

true

The current implementation returns a boolean. Consider implementing JWT tokens for stateless authentication.

User Registration

Create a new user account.

curl -X POST http://localhost:8080/kinconecta/api/user \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Maria Garcia",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "role": "TOURIST",
    "dateOfBirth": "1990-05-15",
    "countryCode": "MX",
    "phoneNumber": "5512345678",
    "phoneE164": "+525512345678",
    "preferedLanguageCode": "ES",
    "accountStatus": "ACTIVE"
  }'

Endpoint: POST /kinconecta/api/user Request Body:

fullName

string

required

User’s complete name

string

required

User’s email address (must be unique)

password

string

required

User’s password (will be hashed with BCrypt)

role

string

required

User role: TOURIST, GUIDE, or ADMIN

dateOfBirth

string

required

Date of birth in format: YYYY-MM-DD

countryCode

string

required

ISO 3166-1 alpha-2 country code (e.g., US, MX, ES)

phoneNumber

string

required

Phone number without country code

phoneE164

string

required

Phone number in E.164 format (e.g., +525512345678)

preferedLanguageCode

string

required

Preferred language code: EN, ES, FR, DE, IT, PT

accountStatus

string

required

Account status: ACTIVE, PENDING_VERIFICATION, SUSPENDED, DEACTIVATED

Response: Returns the created user object:

{
  "id": 1,
  "fullName": "Maria Garcia",
  "email": "[email protected]",
  "role": "TOURIST",
  "dateOfBirth": "1990-05-15",
  "countryCode": "MX",
  "phoneNumber": "5512345678",
  "phoneE164": "+525512345678",
  "preferedLanguageCode": "ES",
  "accountStatus": "ACTIVE",
  "emailVerifiedAt": null,
  "lastLogin": null,
  "createdAt": "2026-03-10T12:00:00Z",
  "updatedAt": "2026-03-10T12:00:00Z"
}

Password is returned in the response. In production, never return password fields in API responses.

User Management Endpoints

Get All Users

Retrieve a list of all registered users.

curl http://localhost:8080/kinconecta/api/user

Endpoint: GET /kinconecta/api/user Response:

[
  {
    "id": 1,
    "fullName": "Maria Garcia",
    "email": "[email protected]",
    "role": "TOURIST",
    "accountStatus": "ACTIVE"
  },
  {
    "id": 2,
    "fullName": "Carlos Rodriguez",
    "email": "[email protected]",
    "role": "GUIDE",
    "accountStatus": "ACTIVE"
  }
]

Get User by ID

Retrieve a specific user by their ID.

curl http://localhost:8080/kinconecta/api/user/Maria_Garcia_1

Endpoint: GET /kinconecta/api/user/{fullName}_{userId} Path Parameters:

fullName

string

required

User’s full name (URL encoded if contains spaces)

userId

long

required

User’s unique identifier

Response:

{
  "id": 1,
  "fullName": "Maria Garcia",
  "email": "[email protected]",
  "role": "TOURIST",
  "dateOfBirth": "1990-05-15",
  "countryCode": "MX",
  "phoneE164": "+525512345678",
  "preferedLanguageCode": "ES",
  "accountStatus": "ACTIVE",
  "createdAt": "2026-03-10T12:00:00Z",
  "updatedAt": "2026-03-10T12:00:00Z"
}

Update User

Update user information.

curl -X PUT http://localhost:8080/kinconecta/api/user/Maria_Garcia_1 \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Maria Garcia Lopez",
    "email": "[email protected]",
    "preferedLanguageCode": "EN"
  }'

Endpoint: PUT /kinconecta/api/user/{fullName}_{userId}

Delete User

Delete a user account.

curl -X DELETE http://localhost:8080/kinconecta/api/user/Maria_Garcia_1

Endpoint: DELETE /kinconecta/api/user/{fullName}_{userId} Response: Returns the deleted user object.

Notifications

Add Notification to User

Add a notification to a user’s notification list.

curl -X POST http://localhost:8080/kinconecta/api/user/1/add-notification \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New booking request",
    "message": "You have a new tour booking request",
    "type": "BOOKING"
  }'

Endpoint: POST /kinconecta/api/user/{userId}/add-notification Path Parameters:

userId

long

required

User’s unique identifier

Request Body:

title

string

required

Notification title

message

string

required

Notification message content

type

string

required

Notification type (e.g., BOOKING, MESSAGE, REVIEW)

Security Best Practices

The following security improvements are recommended before production deployment:

1. Implement JWT Authentication

Replace boolean authentication response with JWT tokens:

@PostMapping("/login")
public ResponseEntity<LoginResponse> login(@RequestBody User credentials) {
    if (userService.validateUser(credentials)) {
        String token = jwtService.generateToken(credentials.getEmail());
        return ResponseEntity.ok(new LoginResponse(token, user));
    }
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}

2. Add Request Validation

@PostMapping
public User addUser(@Valid @RequestBody User user) {
    return userService.addUser(user);
}

3. Implement Role-Based Access Control

httpSecurity.authorizeHttpRequests(
    auth -> auth
        .requestMatchers("/api/admin/**").hasRole("ADMIN")
        .requestMatchers("/api/guide_profiles/**").hasAnyRole("GUIDE", "ADMIN")
        .requestMatchers("/api/user/login", "/api/user").permitAll()
        .anyRequest().authenticated()
)

4. Add Rate Limiting

Implement rate limiting for authentication endpoints:

@RateLimit(requests = 5, perMinutes = 1)
@PostMapping("/login")
public boolean loginUser(@RequestBody User user) {
    return userService.validateUser(user);
}

5. Secure Password Requirements

Enforce strong password policies:

Minimum 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

6. Enable HTTPS

Configure SSL/TLS certificates:

server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-password=${SSL_PASSWORD}
server.ssl.key-store-type=PKCS12

7. Implement Email Verification

Add email verification flow:

@PostMapping("/verify-email")
public ResponseEntity<Void> verifyEmail(@RequestParam String token) {
    userService.verifyEmail(token);
    return ResponseEntity.ok().build();
}

8. Add Session Management

Implement proper session timeout and management:

server.servlet.session.timeout=30m
server.servlet.session.cookie.http-only=true
server.servlet.session.cookie.secure=true

Error Codes

Code	Message	Description
`AUTH001`	Invalid credentials	Email or password is incorrect
`AUTH002`	Account not verified	Email verification required
`AUTH003`	Account suspended	Account has been suspended
`AUTH004`	Account deactivated	Account has been deactivated by user
`AUTH005`	Email already exists	Email is already registered
`AUTH006`	Weak password	Password does not meet security requirements
`AUTH007`	Token expired	Authentication token has expired
`AUTH008`	Invalid token	Authentication token is invalid

Next Steps

API Overview

Return to API overview and explore other endpoints

User Profiles

Learn about tourist and guide profile management

Security Configuration

Deep dive into security implementation

JWT Implementation

Guide to implementing JWT authentication

API Reference

Users

Tours & Bookings

Matching & Communication

Support

Overview

Security Configuration

Password Encoding

CSRF Protection

Request Authorization

User Model

Authentication Endpoints

User Registration

User Management Endpoints

Get All Users

Get User by ID

Update User

Delete User

Notifications

Add Notification to User

Security Best Practices

1. Implement JWT Authentication

2. Add Request Validation

3. Implement Role-Based Access Control

4. Add Rate Limiting

5. Secure Password Requirements

6. Enable HTTPS

7. Implement Email Verification

8. Add Session Management

Error Codes

Next Steps

API Overview

User Profiles

Security Configuration

JWT Implementation

Build docs developers (and LLMs) love

API Reference

Users

Tours & Bookings

Matching & Communication

Support

​Overview

​Security Configuration

​Password Encoding

​CSRF Protection

​Request Authorization

​User Model

​Authentication Endpoints

​User Login

​User Registration

​User Management Endpoints

​Get All Users

​Get User by ID

​Update User

​Delete User

​Notifications

​Add Notification to User

​Security Best Practices

​1. Implement JWT Authentication

​2. Add Request Validation

​3. Implement Role-Based Access Control

​4. Add Rate Limiting

​5. Secure Password Requirements

​6. Enable HTTPS

​7. Implement Email Verification

​8. Add Session Management

​Error Codes

​Next Steps

API Overview

User Profiles

Security Configuration

JWT Implementation

Build docs developers (and LLMs) love

Overview

Security Configuration

Password Encoding

CSRF Protection

Request Authorization

User Model

Authentication Endpoints

User Login

User Registration

User Management Endpoints

Get All Users

Get User by ID

Update User

Delete User

Notifications

Add Notification to User

Security Best Practices

1. Implement JWT Authentication

2. Add Request Validation

3. Implement Role-Based Access Control

4. Add Rate Limiting

5. Secure Password Requirements

6. Enable HTTPS

7. Implement Email Verification

8. Add Session Management

Error Codes

Next Steps