Base URL: /api/auth
The authentication system uses JWT (JSON Web Tokens) for secure API access. Registration requires a 6-digit registration code tied to your email address.
Register a new user account.
Request:
{
"username": "johndoe",
"email": "john@example.com",
"password": "SecurePass123!",
"registrationCode": "ABC123",
"firstName": "John",
"lastName": "Doe"
}
Validation:
username: Minimum 3 characters, alphanumeric
email: Valid email format
password: Minimum 6 characters
registrationCode: Exactly 6 characters, must be valid for the provided email
firstName, lastName: Optional
Success Response (201):
{
"message": "User created successfully",
"user": {
"id": "uuid",
"username": "johndoe",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Notes:
TrialStartDate, TrialEndDate, and SubscriptionStatus: 'TRIAL'
Error Responses:
400 - Validation Error:
{
"message": "Validation failed: username must be at least 3 characters",
"errors": [...]
}
400 - Invalid Registration Code:
{
"message": "Invalid or expired registration code. Please get your personalized code using your email address.",
"field": "registrationCode"
}
400 - User Already Exists:
{
"message": "User already exists"
}
---
Authenticate and receive a JWT token.
Request:
{
"username": "johndoe",
"password": "SecurePass123!"
}
Success Response (200):
{
"message": "Login successful",
"user": {
"id": "uuid",
"username": "johndoe",
"email": "john@example.com",
"firstName": "John",
"lastName": "Doe"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Error Responses:
401 - Invalid Credentials:
{
"message": "Invalid username or password"
}
500 - Server Error:
{
"message": "Internal server error"
}
---
Verify a JWT token and get user information.
Headers:
Authorization: Bearer Success Response (200):
{
"valid": true,
"user": {
"id": "uuid",
"username": "johndoe",
"email": "john@example.com"
}
}
Error Response (401):
{
"valid": false,
"message": "Invalid or expired token"
}
---
Logout (client-side token removal - stateless JWT).
Headers:
Authorization: Bearer Response (200):
{
"message": "Logout successful"
}
Note: With JWT, logout is primarily client-side. Remove the token from storage.
---
Registration codes are personalized to email addresses with a 24-hour grace period:
Request Registration Code:
POST /api/auth/request-code
Content-Type: application/json
{
"email": "john@example.com"
}
Response:
{
"message": "Registration code sent to your email",
"codeRequested": true
}
The code will be emailed to the provided address.
---
JWT tokens contain:
All authenticated endpoints require the token in the Authorization header:
fetch('http://localhost:3001/api/data', {
headers: {
'Authorization': 'Bearer ' + token,
'Content-Type': 'application/json'
}
})
Tokens expire after 7 days. When you receive a 401 error with "Invalid or expired token", request a new token by logging in again.
---
---
Authentication endpoints have strict rate limiting:
If you exceed this limit, you'll receive:
{
"message": "Too many authentication attempts from this IP, please try again later."
}
Wait 15 minutes before trying again.
---
---
// 1. Request registration code
await fetch('http://localhost:3001/api/auth/request-code', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: 'john@example.com' })
});
// 2. Check email for code, then register
const registerResponse = await fetch('http://localhost:3001/api/auth/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
username: 'johndoe',
email: 'john@example.com',
password: 'SecurePass123!',
registrationCode: 'ABC123',
firstName: 'John',
lastName: 'Doe'
})
});
const { token, user } = await registerResponse.json();
localStorage.setItem('jwt_token', token);
// 3. Use token for authenticated requests
const dataResponse = await fetch('http://localhost:3001/api/data', {
headers: {
'Authorization': Bearer ${token},
'Content-Type': 'application/json'
}
});