Skip to main content
The authentication endpoints allow users to register new accounts and log in to existing accounts. Both endpoints return a JWT token that must be included in subsequent authenticated requests.

​
Register New User

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securepassword123"
  }'

​
Endpoint

POST /api/auth/register

​
Request Body

​
name
string
required
User’s full name. Maximum 100 characters.
​
email
string
required
Valid email address. Must be unique in the system.
​
password
string
required
User password. Must be at least 8 characters long. Will be hashed using BCrypt with strength 12.

​
Response

​
token
string
JWT Bearer token (HS256, 24-hour validity). Include this in the Authorization header as Bearer <token> for authenticated requests.
​
name
string
The registered user’s name.
​
email
string
The registered user’s email address (matches the JWT subject).

​
Status Codes

​
201 Created
Success
User successfully registered. Returns JWT token and user details.
​
400 Bad Request
Error
Invalid input data. Response includes field-level validation errors.
​
409 Conflict
Error
Email address already registered.

​
Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "John Doe",
  "email": "john@example.com"
}

​
Login User

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "securepassword123"
  }'

​
Endpoint

POST /api/auth/login

​
Request Body

​
email
string
required
Registered email address.
​
password
string
required
User password.

​
Response

​
token
string
JWT Bearer token (HS256, 24-hour validity). Include this in the Authorization header as Bearer <token> for authenticated requests.
​
name
string
The authenticated user’s name.
​
email
string
The authenticated user’s email address (matches the JWT subject).

​
Status Codes

​
200 OK
Success
User successfully authenticated. Returns JWT token and user details.
​
400 Bad Request
Error
Invalid input data (e.g., malformed email).
​
401 Unauthorized
Error
Invalid credentials (email not found or incorrect password).

​
Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "name": "John Doe",
  "email": "john@example.com"
}

​
Authentication Flow

  1. Register or Login: Call /api/auth/register or /api/auth/login to obtain a JWT token
  2. Store Token: Save the token securely (e.g., localStorage, secure cookie)
  3. Include in Requests: Add the token to the Authorization header for authenticated endpoints: 
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  4. Token Expiry: Tokens expire after 24 hours. Request a new token by logging in again

​
Security Notes

  • Passwords are hashed using BCrypt with strength 12 (OWASP recommendation)
  • JWT tokens are signed with HS256 algorithm
  • Default token expiration: 24 hours (configurable via JWT_EXPIRATION_MS environment variable)
  • The JWT secret key must be at least 32 characters and stored securely (use AWS SSM Parameter Store in production)

Build docs developers (and LLMs) love

Get started for freeTalk to us