Developer Documentation: User Authentication API
Overview
The User Authentication API provides secure user registration, login, and session management functionality. This RESTful API uses JWT tokens for authentication and includes role-based access control.
Base URL: https://api.example.com/v1
API Version: 1.0
Authentication: Bearer Token (JWT)
Quick Start
1. Register a New User
curl -X POST https://api.example.com/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!",
"firstName": "John",
"lastName": "Doe"
}'
2. Login
curl -X POST https://api.example.com/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!"
}'
3. Access Protected Resources
curl -X GET https://api.example.com/v1/user/profile \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
API Endpoints
Authentication Endpoints
POST /auth/register
Creates a new user account.
Request Body:
{
"email": "string (required)",
"password": "string (required)",
"firstName": "string (required)",
"lastName": "string (required)"
}
Password Requirements:
- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character
Response (201 Created):{
"success": true,
"data": {
"user": {
"id": "12345",
"email": "user@example.com",
"firstName": "John",
"lastName": "Doe",
"role": "user",
"createdAt": "2024-01-15T10:30:00Z"
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
POST /auth/login
Authenticates a user and returns a JWT token.
Request Body:
{
"email": "string (required)",
"password": "string (required)"
}
Response (200 OK):
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"user": {
"id": "12345",
"email": "user@example.com",
"role": "user"
}
}
}
POST /auth/refresh
Refreshes an expired JWT token.
Request Body:
{
"refreshToken": "string (required)"
}
Response (200 OK):
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
}
}
POST /auth/logout
Invalidates the current session.
Headers:
Authorization: Bearer <token>
Response (200 OK):
{
"success": true,
"message": "Successfully logged out"
}
User Management Endpoints
GET /user/profile
Retrieves the current user's profile information.
Headers:
Authorization: Bearer <token>
**Response (