Auth Service – API Reference 🔐
This document describes the public authentication APIs exposed by the Auth Service in ShopVerse.
All authentication APIs are accessed via the API Gateway.
🌐 Base URL
/api/auth
🔐 Authentication Overview
- Auth Service issues JWT tokens
- JWT is validated at the API Gateway
- Downstream services rely on trusted headers
- Tokens follow a stateless authentication model
📌 Register User
Create a new user account.
➤ Endpoint
POST /api/auth/register
➤ Request Body
{
"fullName": "John Doe",
"email": "john@example.com",
"phoneNo": "9876543210",
"password": "StrongPassword123"
}
➤ Success Response (201 CREATED)
{
"message": "User registered successfully"
}
➤ Error Responses
| Status | Reason |
|---|---|
| 400 | Invalid input |
| 409 | Email already exists |
| 500 | Internal server error |
🔑 Login User
Authenticate user and issue JWT token.
➤ Endpoint
POST /api/auth/login
➤ Request Body
{
"email": "john@example.com",
"password": "StrongPassword123"
}
➤ Success Response (200 OK)
{
"token": "eyJhbGciOiJIUzUxMiJ9...",
"type": "Bearer"
}
➤ Error Responses
| Status | Reason |
|---|---|
| 401 | Invalid credentials |
| 404 | User not found |
| 500 | Internal server error |
🧾 JWT Token Details
Token Format
Authorization: Bearer <JWT_TOKEN>
JWT Claims
{
"sub": "john@example.com",
"role": "CUSTOMER",
"name": "John Doe",
"iat": 1710000000,
"exp": 1710003600
}
| Claim | Description |
|---|---|
sub | User email (identity) |
role | User role |
exp | Token expiration |
🔄 Authentication Flow Summary
📡 Events Published
| Event | Topic | Description |
|---|---|---|
| USER_REGISTERED | auth-events | New user registration |
| USER_LOGIN | auth-events | User login activity |
These events are consumed by:
- Notification Service
- Analytics Service
🛡️ Security Notes
- Passwords are never stored or logged in plain text
- BCrypt is used for password hashing
- JWT uses HS512 signing
- Token expiration is enforced
- Auth APIs are rate-limit ready
⚠️ Common Issues
❌ Invalid Token
- Token expired or tampered
- Re-login required
❌ Multiple Login Attempts
- Invalid credentials return generic error
- Prevents user enumeration
📌 Summary
The Auth API provides:
- Secure user authentication
- Stateless JWT-based authorization
- Clean integration with API Gateway
- Event-driven extensibility
It serves as the entry point for security in ShopVerse.