Skip to main content

​
Quickstart Guide

This guide will help you set up the User Management System API locally and make your first authenticated requests. You’ll be up and running in less than 10 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Java 17 or higher installed
  • Maven 3.6+ for dependency management
  • Git to clone the repository
  • A REST client like cURL, Postman, or HTTPie
For production deployment, you’ll also need MySQL 8.0+. For development, the system uses an in-memory H2 database with no setup required.

​
Installation

1

Clone the repository

Clone the User Management System repository to your local machine:
git clone https://github.com/JuanSotoSegovia/apiREST-userManagementSystem.git
cd apiREST-userManagementSystem
2

Configure the environment profile

The system supports two profiles: dev (H2 database) and prod (MySQL). For quickstart, use the development profile.Open src/main/resources/application.properties and verify the active profile:
spring.application.name=userManagementSystem
spring.profiles.active=dev
The dev profile uses an in-memory H2 database that’s automatically created on startup with pre-loaded test users.

​
Development Profile (H2)

No configuration needed! The development profile (application-dev.properties) comes pre-configured:
spring.datasource.url=jdbc:h2:mem:usermanagementdb
spring.datasource.username=sa
spring.datasource.password=

jwt.secret=dev_secret
jwt.expiration=86400000

​
Production Profile (MySQL)

For production deployment, set spring.profiles.active=prod and configure MySQL in application-prod.properties:
spring.datasource.url=jdbc:mysql://localhost:3306/user_management
spring.datasource.username=root
spring.datasource.password=admin

jwt.secret=prod_secret
jwt.expiration=86400000
Always change the jwt.secret value in production to a strong, randomly generated secret.
3

Start the application

Run the application using Maven:
mvn spring-boot:run
You should see output indicating the application has started:
Started UserManagementSystemApplication in 3.456 seconds
The API is now running at http://localhost:8080
4

Verify the setup

Test that the API is accessible by checking the health of the auth endpoint:
curl http://localhost:8080/auth/signup
You should receive a 400 Bad Request response (expected, since we didn’t send a body), confirming the endpoint is active.

​
Make Your First API Call

Now that the API is running, let’s create a user account and authenticate.

​
1. Register a New User

Create a new user account by sending a POST request to /auth/signup: 
curl -X POST http://localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "[email protected]",
    "password": "SecurePass123"
  }'
Request Body Requirements (from CreateUserDTO.java:10):
  • username: 3-20 characters, required
  • email: Valid email format, required
  • password: 8-16 characters, must contain at least one number, one lowercase letter, and one uppercase letter
Response (201 Created): 
{
  "id": 3,
  "username": "johndoe",
  "email": "[email protected]"
}
The password is automatically hashed using BCrypt before storage (configured in SecurityConfig.java:38).

​
2. Login and Get JWT Token

Authenticate with your credentials to receive a JWT token: 
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
  }'
Response (200 OK): 
{
  "id": 3,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huLmRvZUBleGFtcGxlLmNvbSIsInJvbGVzIjpbIlJPTEVfVVNFUiJdLCJpYXQiOjE3MDk0OTYwMDAsImV4cCI6MTcwOTU4MjQwMH0.Xm9kZUlkZW50aWZpZXI",
  "username": "johndoe",
  "email": "[email protected]"
}
Save the token value - you’ll need it to authenticate subsequent requests to protected endpoints.

​
3. Access Protected Endpoints

Use the JWT token to access protected resources. Include it in the Authorization header:
cURL
curl -X GET http://localhost:8080/users/me \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123"
  }'
Response (200 OK): 
{
  "id": 3,
  "username": "johndoe",
  "email": "[email protected]",
  "role": "ROLE_USER"
}

​
Pre-loaded Test Users

In development mode, the system comes with two pre-loaded users (defined in data.sql):
UsernameEmailPasswordRole
admin-user[email protected]Admin1234ROLE_ADMIN
normal-user[email protected]NorUs1234ROLE_USER
You can use these accounts to test admin-level endpoints: 
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Admin1234"
  }'
Then access the admin endpoint to list all users: 
curl -X GET http://localhost:8080/admin/users \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
The /admin/users endpoint requires ROLE_ADMIN (configured in SecurityConfig.java:30). Regular users will receive a 403 Forbidden response.

​
Common Validation Errors

The API validates all inputs. Here are common errors you might encounter: Invalid Email Format: 
{
  "email": "El email debe ser valido"
}
Weak Password: 
{
  "password": "La password debe tener al menos una numero, una letra minuscula y una letra mayuscula"
}
Username Too Short: 
{
  "username": "El username debe tener entre 3 y 20 caracteres"
}

​
Next Steps

Now that you have the API running, explore these resources:

API Reference

Explore all endpoints, request schemas, and response formats

Authentication Guide

Deep dive into JWT authentication and authorization

Configuration

Learn about environment variables, database setup, and security config

Error Handling

Understand error responses and how to handle them

​
Need Help?

If you encounter issues:
  • Check that Java 17+ is installed: java -version
  • Verify Maven is available: mvn -version
  • Ensure port 8080 is not in use
  • Review application logs for detailed error messages
  • For production MySQL setup, verify database connectivity and credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us