Overview#
The Auth Service provides comprehensive authentication and authorization functionality for the Lilith platform. It implements industry-standard security practices including JWT tokens, password hashing, role-based access control (RBAC), and secure session management.
Base URL#
- Development:
http://localhost:8081 - Staging:
https://auth.staging.lilith.app - Production:
https://auth.lilith.app
Authentication#
Most endpoints require authentication via JWT token in the Authorization header:
Authorization: Bearer <jwt_token>
Health Check#
GET /health#
Check service health and status.
Response: 200 OK
{
"status": "healthy",
"service": "auth",
"timestamp": "2025-01-28T12:00:00.000Z",
"version": "1.0.0",
"database": "connected",
"users_count": 1234
}
User Registration#
POST /auth/register#
Register a new user account.
Request Body:
{
"email": "user@example.com",
"password": "SecurePassword123!",
"name": "John Doe",
"username": "johndoe"
}
Validation:
email: Valid email format, uniquepassword: Minimum 8 characters, contains uppercase, lowercase, number, special charactername: 1-100 charactersusername: 3-30 characters, alphanumeric + underscore/dash
Response: 201 Created
{
"success": true,
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"username": "johndoe",
"verified": false,
"createdAt": "2025-01-28T12:00:00.000Z",
"roles": ["user"]
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": "1h"
}
}
Error Responses:
400 Bad Request: Invalid input data409 Conflict: Email already exists
User Login#
POST /auth/login#
Authenticate a user and receive access token.
Request Body:
{
"email": "user@example.com",
"password": "SecurePassword123!"
}
Response: 200 OK
{
"success": true,
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"username": "johndoe",
"verified": true,
"lastLogin": "2025-01-28T12:00:00.000Z",
"roles": ["user"]
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": "1h"
}
}
Error Responses:
400 Bad Request: Missing email or password401 Unauthorized: Invalid credentials423 Locked: Account temporarily locked
Token Management#
POST /auth/refresh#
Refresh an access token using a refresh token.
Request Body:
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Response: 200 OK
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": "1h"
}
}
POST /auth/logout#
Logout and invalidate tokens.
Headers: Authorization: Bearer <token>
Response: 200 OK
{
"success": true,
"message": "Successfully logged out"
}
User Profile Management#
GET /auth/profile#
Get current user profile information.
Headers: Authorization: Bearer <token>
Response: 200 OK
{
"success": true,
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"username": "johndoe",
"verified": true,
"createdAt": "2025-01-28T12:00:00.000Z",
"lastLogin": "2025-01-28T12:00:00.000Z",
"roles": ["user"],
"preferences": {
"theme": "dark",
"notifications": true
}
}
}
}
PUT /auth/profile#
Update user profile information.
Headers: Authorization: Bearer <token>
Request Body:
{
"name": "John Smith",
"username": "johnsmith",
"preferences": {
"theme": "light",
"notifications": false
}
}
Response: 200 OK
{
"success": true,
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Smith",
"username": "johnsmith",
"verified": true,
"updatedAt": "2025-01-28T12:00:00.000Z"
}
}
}
Password Management#
PUT /auth/password#
Change user password.
Headers: Authorization: Bearer <token>
Request Body:
{
"currentPassword": "OldPassword123!",
"newPassword": "NewPassword456!"
}
Response: 200 OK
{
"success": true,
"message": "Password updated successfully"
}
POST /auth/forgot-password#
Request password reset email.
Request Body:
{
"email": "user@example.com"
}
Response: 200 OK
{
"success": true,
"message": "Password reset email sent"
}
POST /auth/reset-password#
Reset password using reset token.
Request Body:
{
"resetToken": "reset_token_123",
"newPassword": "NewPassword789!"
}
Response: 200 OK
{
"success": true,
"message": "Password reset successfully"
}
Email Verification#
POST /auth/verify-email#
Verify email address using verification token.
Request Body:
{
"verificationToken": "verify_token_456"
}
Response: 200 OK
{
"success": true,
"message": "Email verified successfully"
}
POST /auth/resend-verification#
Resend email verification.
Headers: Authorization: Bearer <token>
Response: 200 OK
{
"success": true,
"message": "Verification email sent"
}
Role-Based Access Control (RBAC)#
GET /auth/roles#
Get available roles and permissions.
Headers: Authorization: Bearer <token> (Admin required)
Response: 200 OK
{
"success": true,
"data": {
"roles": [
{
"name": "user",
"description": "Standard user",
"permissions": ["read:profile", "update:profile"]
},
{
"name": "moderator",
"description": "Content moderator",
"permissions": ["read:content", "moderate:content"]
},
{
"name": "admin",
"description": "System administrator",
"permissions": ["*"]
}
]
}
}
PUT /auth/users/:userId/roles#
Update user roles (Admin only).
Headers: Authorization: Bearer <token> (Admin required)
Request Body:
{
"roles": ["user", "moderator"]
}
Response: 200 OK
{
"success": true,
"data": {
"userId": "usr_1234567890",
"roles": ["user", "moderator"],
"updatedAt": "2025-01-28T12:00:00.000Z"
}
}
Session Management#
GET /auth/sessions#
Get active user sessions.
Headers: Authorization: Bearer <token>
Response: 200 OK
{
"success": true,
"data": {
"sessions": [
{
"id": "sess_123",
"deviceType": "desktop",
"browser": "Chrome",
"location": "New York, US",
"lastActive": "2025-01-28T12:00:00.000Z",
"current": true
}
]
}
}
DELETE /auth/sessions/:sessionId#
Terminate a specific session.
Headers: Authorization: Bearer <token>
Response: 200 OK
{
"success": true,
"message": "Session terminated"
}
User Management (Admin)#
GET /auth/users#
List users with filtering and pagination.
Headers: Authorization: Bearer <token> (Admin required)
Query Parameters:
page: Page number (default: 1)limit: Items per page (default: 20, max: 100)search: Search by email, name, or usernamerole: Filter by roleverified: Filter by verification status
Response: 200 OK
{
"success": true,
"data": {
"users": [
{
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"username": "johndoe",
"verified": true,
"roles": ["user"],
"createdAt": "2025-01-28T12:00:00.000Z",
"lastLogin": "2025-01-28T12:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1234,
"totalPages": 62
}
}
}
GET /auth/users/:userId#
Get specific user details.
Headers: Authorization: Bearer <token> (Admin or own profile)
Response: 200 OK
{
"success": true,
"data": {
"user": {
"id": "usr_1234567890",
"email": "user@example.com",
"name": "John Doe",
"username": "johndoe",
"verified": true,
"roles": ["user"],
"createdAt": "2025-01-28T12:00:00.000Z",
"lastLogin": "2025-01-28T12:00:00.000Z",
"metadata": {}
}
}
}
PUT /auth/users/:userId/status#
Update user status (Admin only).
Headers: Authorization: Bearer <token> (Admin required)
Request Body:
{
"status": "active", // active, suspended, banned
"reason": "Policy violation"
}
Response: 200 OK
{
"success": true,
"data": {
"userId": "usr_1234567890",
"status": "suspended",
"reason": "Policy violation",
"updatedAt": "2025-01-28T12:00:00.000Z"
}
}
API Keys (For Service-to-Service)#
POST /auth/api-keys#
Create API key for service authentication.
Headers: Authorization: Bearer <token> (Admin required)
Request Body:
{
"name": "Content Service API Key",
"scopes": ["read:users", "update:users"],
"expiresAt": "2025-12-31T23:59:59.000Z"
}
Response: 201 Created
{
"success": true,
"data": {
"id": "key_123456",
"name": "Content Service API Key",
"key": "sk_live_abc123def456...",
"scopes": ["read:users", "update:users"],
"expiresAt": "2025-12-31T23:59:59.000Z",
"createdAt": "2025-01-28T12:00:00.000Z"
}
}
GET /auth/api-keys#
List API keys.
Headers: Authorization: Bearer <token> (Admin required)
Response: 200 OK
{
"success": true,
"data": {
"apiKeys": [
{
"id": "key_123456",
"name": "Content Service API Key",
"scopes": ["read:users", "update:users"],
"lastUsed": "2025-01-28T11:00:00.000Z",
"expiresAt": "2025-12-31T23:59:59.000Z"
}
]
}
}
Error Responses#
All error responses follow this format:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": "Additional error context"
}
}
Common Error Codes#
VALIDATION_ERROR: Invalid input dataUNAUTHORIZED: Authentication requiredFORBIDDEN: Insufficient permissionsNOT_FOUND: Resource not foundCONFLICT: Resource already existsRATE_LIMITED: Too many requestsSERVER_ERROR: Internal server error
Rate Limiting#
The API implements rate limiting to prevent abuse:
- Registration: 5 attempts per hour per IP
- Login: 10 attempts per 15 minutes per IP
- Password Reset: 3 attempts per hour per email
- General API: 1000 requests per hour per authenticated user
Rate limit headers are included in responses:
X-RateLimit-Limit: Request limitX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Reset timestamp
Security Features#
Password Security#
- BCrypt hashing with salt rounds: 12
- Password strength requirements enforced
- Password history to prevent reuse
Token Security#
- JWT tokens with RS256 signing
- Short-lived access tokens (1 hour)
- Secure refresh token rotation
- Token blacklisting on logout
Account Security#
- Failed login attempt tracking
- Account lockout after 5 failed attempts
- IP-based suspicious activity detection
- Email notifications for security events
Data Protection#
- Input validation and sanitization
- SQL injection prevention
- XSS protection
- CORS configuration
- Secure headers
Integration Examples#
cURL Examples#
Register User:
curl -X POST https://auth.lilith.app/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePassword123!",
"name": "John Doe"
}'
Login:
curl -X POST https://auth.lilith.app/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePassword123!"
}'
Get Profile:
curl -X GET https://auth.lilith.app/auth/profile \
-H "Authorization: Bearer <token>"
JavaScript SDK#
import { AuthService } from '@lilith/sdk';
const auth = new AuthService({
baseUrl: 'https://auth.lilith.app'
});
// Register
const { user, token } = await auth.register({
email: 'user@example.com',
password: 'SecurePassword123!',
name: 'John Doe'
});
// Login
const { user, token } = await auth.login({
email: 'user@example.com',
password: 'SecurePassword123!'
});
// Get profile
const profile = await auth.getProfile(token);
Support#
For API support or questions:
- Documentation: https://docs.lilith.app/auth
- Support: support@lilith.app
- Status: https://status.lilith.app
Last Updated: 2025-01-28 API Version: 1.0.0