🔐 JWT Auth

Stateless JWT authentication service with user registration, login, and access/refresh token management.
Supports two token delivery modes: HTTP-only cookies (v1) and JSON body (v2).

---

Quick Start

cp example.env .env        # fill in your values
docker compose up -d       # start PostgreSQL
./gradlew bootRun          # run the app on :8080

Environment Variables

POSTGRES_DB=jwt_auth
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret
POSTGRES_HOST=localhost
JWT_SECRET_KEY=your_base64_secret
JWT_COOKIE_DOMAIN=localhost

---

API Versioning

Endpoints are versioned via the API-Version header. Default is 1.

API-Version: 2

---

Endpoints

POST /api/users

Register a new user.

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"username": "john_doe", "password": "Str0ng!Pass"}'

{
  "message": "Success",
  "data": { "id": "uuid", "username": "john_doe", "roles": ["USER"] }
}

Field	Rules
username	3–16 chars, letters / numbers / ._-
password	8–72 chars, must include uppercase, lowercase, digit, special char

---

POST /api/auth/tokens

Get tokens as HTTP-only cookies. Supports PASSWORD and REFRESH_TOKEN grant types.

# Login
curl -X POST http://localhost:8080/api/auth/tokens \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"grantType": "PASSWORD", "username": "john_doe", "password": "Str0ng!Pass"}'

# Refresh
curl -X POST http://localhost:8080/api/auth/tokens \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"grantType": "REFRESH_TOKEN"}'

---

POST /api/auth/tokens

Get tokens in the response body. Refresh token is sent via the refresh request header.

# Login
curl -X POST http://localhost:8080/api/auth/tokens \
  -H "Content-Type: application/json" \
  -H "API-Version: 2" \
  -d '{"grantType": "PASSWORD", "username": "john_doe", "password": "Str0ng!Pass"}'

# Refresh
curl -X POST http://localhost:8080/api/auth/tokens \
  -H "Content-Type: application/json" \
  -H "API-Version: 2" \
  -H "refresh: <your_refresh_token>" \
  -d '{"grantType": "REFRESH_TOKEN"}'

{
  "message": "Success",
  "data": { "accessToken": "eyJ...", "refreshToken": "eyJ..." }
}

---

DELETE /api/auth/tokens/current

Logout — revokes the refresh token and clears cookies.

curl -X DELETE http://localhost:8080/api/auth/tokens/current -b cookies.txt

---

GET /api/users/me

Get the authenticated user's profile.

curl http://localhost:8080/api/users/me -b cookies.txt

{
  "message": "Success",
  "data": { "id": "uuid", "username": "john_doe", "roles": ["USER"] }
}

---

Summary

Method	Path	Ver	Auth	Description
POST	/api/users	1	❌	Register user
POST	/api/auth/tokens	1	❌	Tokens via cookies
POST	/api/auth/tokens	2	❌	Tokens via body
DELETE	/api/auth/tokens/current	1	❌	Logout
GET	/api/users/me	1	✅	Current user