Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/auth-service/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through running Auth Service on your local machine from a clean clone to an authenticated API call. By the end you will have PostgreSQL, MailHog, and Redpanda running in Docker, the service itself running on port 8080, and a valid JWT access token you can use to call protected endpoints. The whole flow takes under 5 minutes assuming Docker is already running.
1

Install prerequisites

Make sure the following tools are available on your machine before continuing:
ToolMinimum versionNotes
Java21The Maven wrapper (./mvnw) downloads Maven automatically
Maven3.9+Only needed if you prefer your own Maven installation over ./mvnw
Docker + Docker ComposeAny recent versionRequired for PostgreSQL, MailHog, and Redpanda
Verify your Java version:
java -version
# Expected: openjdk version "21.x.x" ...
2

Clone and configure environment variables

Clone the repository and copy the example environment file:
git clone https://github.com/ricardomb-tech/auth-service.git
cd auth-service
cp .env.example .env
Open .env and set at minimum JWT_SECRET_CURRENT to a random 256-bit (32-byte) secret. All other values have working dev defaults:
# .env — minimum required change for local dev
JWT_SECRET_CURRENT=your-256-bit-random-secret-goes-here-change-this

# Database (defaults match docker-compose.yml — no change needed for dev)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=auth_service
DB_USER=auth_service
DB_PASSWORD=auth_service

# Email — dev uses MailHog on port 1025 (started by docker-compose)
MAIL_HOST=localhost
MAIL_PORT=1025

# OAuth2 — leave blank for now; social login is optional for quickstart
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Kafka-compatible broker (Redpanda, started by docker-compose)
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

APP_BASE_URL=http://localhost:8080
Never commit your .env file. It is already listed in .gitignore. In the prod profile there are no default values — missing variables cause a fast-fail startup by design.
3

Start dependencies with Docker Compose

Start PostgreSQL 15, MailHog, and Redpanda in the background:
docker-compose up -d
This brings up three services defined in docker-compose.yml:
ServicePortPurpose
postgres5432Primary database; Flyway runs migrations on first startup
mailhog1025 (SMTP), 8025 (Web UI)Captures outgoing emails in dev so you can read verification tokens
redpanda9092Kafka-compatible broker; staged for the transactional outbox (Epic 6)
Verify that all containers are healthy:
docker-compose ps
# All three services should show "running" or "healthy"
Open http://localhost:8025 in your browser to access the MailHog web UI. Every verification email sent by Auth Service will appear here — there is no real email delivery in dev mode.
4

Run the service

Start Auth Service using the dev Spring profile, which picks up the application-dev.properties defaults and connects to the Docker Compose services:
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
Flyway automatically applies all pending migrations (V1 through V4) on first startup. Watch for this line in the logs to confirm the service is ready:
Started AuthServiceApplication in X.XXX seconds
The REST API is now available at http://localhost:8080.
The interactive Swagger UI is available at http://localhost:8080/swagger-ui.html. You can explore and try every endpoint directly from your browser without writing any curl commands.
5

Register, verify, and log in

Follow this three-request workflow to obtain a JWT access token.1. Register a new account
curl -s -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "SuperSecret123!"}' | jq .
The response is intentionally generic regardless of whether the email already exists (anti-enumeration):
{
  "message": "Si el email es válido, recibirás un correo de verificación."
}
2. Retrieve the verification token from MailHogOpen http://localhost:8025 in your browser. You will see an email from Auth Service containing a verification token. Copy the token value from the email body.3. Verify your account
curl -s -X POST http://localhost:8080/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "<your-verification-token-from-mailhog>"}' | jq .
A successful response confirms the account is now ACTIVE:
{
  "message": "Tu cuenta ha sido verificada. Ya puedes iniciar sesión."
}
4. Log in and obtain tokens
curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "SuperSecret123!"}' | jq .
Auth Service returns an access token (JWT, 15-minute TTL) and an opaque refresh token (7-day TTL):
{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "a1b2c3d4e5f6...",
  "tokenType": "Bearer",
  "expiresInSeconds": 900
}
5. Call a protected endpointPass the accessToken in the Authorization header to call any protected route:
curl -s http://localhost:8080/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." | jq .
The response returns your account profile:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "alice@example.com",
  "roles": ["USER"],
  "status": "ACTIVE",
  "federatedIdentities": [],
  "createdAt": "2026-07-01T12:00:00Z"
}
Access tokens expire after 900 seconds (15 minutes). Use POST /auth/refresh with your refreshToken to rotate it and receive a new access token without logging in again. If you present a refresh token that has already been used, Auth Service will revoke the entire token family — you will need to log in again.

​
Next steps

  • Read the Architecture overview to understand the Clean Architecture layers, JWT design decisions, and refresh token family rotation.
  • Configure Google and GitHub OAuth2 credentials in .env and try the social login flow at /oauth2/authorization/google or /oauth2/authorization/github.
  • Run the full test suite (unit, integration, and ArchUnit architecture tests) with: 
    ./mvnw test
    Integration tests that use Testcontainers require Docker to be running and are skipped automatically when Docker is unavailable.

Build docs developers (and LLMs) love

Get started for freeTalk to us