My Profile Authentication API

This documentation covers all authentication endpoints for the My Profile platform. All endpoints follow OAuth 2.0 principles and implement industry security best practices.

🔐 Security Features

  • Rate limiting on sensitive endpoints
  • JWT-based authentication with token rotation
  • Two-factor authentication support
  • IP and device tracking
  • Brute force prevention
  • Session management
POST /api/auth/register

Register a new user account with email or phone verification.

Request Parameters
Parameter Type Description
emailrequired string Valid email address
passwordrequired string Min 8 chars, must include uppercase, lowercase, number, special char
fullNamerequired string Full name (min 2 characters)
usernamerequired string Username (letters, numbers, underscores only)
accountTyperequired enum "MYSELF" or "SOMEONE_ELSE"
phoneNumberrequired string
accountCategoryrequired enum "PRIMARY_ACCOUNT" or "SECONDARY_ACCOUNT"
dateOfBirthrequired string ISO date format
countryOfResidencerequired string Country name
verificationMethodrequired enum "EMAIL" or "PHONE"
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/register
                    -H "Content-Type: application/json"
                    -d '{
                        "email": "user@example.com",
                        "password": "SecureP@ss123",
                        "fullName": "John Doe",
                        "username": "johndoe",
                        "accountType": "MYSELF",
                        "dateOfBirth": "1990-01-01",
                        "phoneNumber": "+237693028598",
                        "countryOfResidence": "United States",
                        "verificationMethod": "EMAIL",
                        "accountCategory": "PRIMARY_ACCOUNT"
                    }'
Success Response (200 OK)
{
    "success": true,
    "message": "Registration successful",
    "userId": "5f9d88b...",
    "verificationMethod": "EMAIL",
    "otpRequired": true,
    "otpChannel": "email"
}
Error Responses
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input data",
        "details": {
            "email": "Must be a valid email address",
            "password": "Must meet password requirements"
        }
    }
}
Status Description
400 Invalid input data
409 Email already registered
429 Too many requests
GET /api/auth/check-email/:email

Check if an email address is available for registration.

URL Parameters
Parameter Type Description
emailrequired string Email address to check
Example Request
curl -X GET https://my-profile-server-api.onrender.com/api/auth/check-email/user@example.com
Success Response (200 OK)
{
    "available": true,
    "message": "Email is available"
}
Error Response
{
    "available": false,
    "message": "Email is already registered"
}
GET /api/auth/check-username/:username

Check if a username is available for registration.

URL Parameters
Parameter Type Description
usernamerequired string Username to check
Example Request
curl -X GET https://my-profile-server-api.onrender.com/api/auth/check-username/johndoe
Success Response (200 OK)
{
    "available": true,
    "message": "Username is available"
}
Error Response
{
    "available": false,
    "message": "Username is already taken"
}
POST /api/auth/trouble-login

Get help with login issues and receive personalized assistance.

Request Parameters
Parameter Type Description
emailrequired string Email address associated with the account
issuerequired string Type of login issue: 'forgot_password', 'account_locked', '2fa_issues', or 'other'
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/trouble-login \
-H "Content-Type: application/json" \
-d {
    "email": "user@example.com",
    "issue": "forgot_password"
}
Success Response (200 OK)
{
    "success": true,
    "message": "We've identified some steps to help you log in",
    "nextSteps": [
        "Check your email for password reset instructions",
        "Follow the link in the email to create a new password",
        "If you don't receive the email, check your spam folder"
    ],
    "supportEmail": "support@myprofile.ltd",
    "supportPhone": "+237693028598"
}
Error Response
{
    "success": false,
    "message": "Error processing your request. Please try again later."
}
Status Description
500 Internal server error
POST /api/auth/login

Authenticate user and receive access/refresh tokens.

Rate Limiting: 5 attempts per 15 minutes
Request Parameters
Parameter Type Description
emailrequired string User's email address
passwordrequired string User's password
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/login \
-H "Content-Type: application/json" \
-d {
    "email": "user@example.com",
    "password": "SecureP@ss123"
}
Success Response (200 OK)
{
    "success": true,
    "user": {
        "id": "5f9d88b...",
        "email": "user@example.com",
        "fullName": "John Doe"
    },
    "tokens": {
        "accessToken": "eyJhbG...",
        "refreshToken": "eyJhbG..."
    }
}
Error Responses
{
    "success": false,
    "error": {
        "code": "INVALID_CREDENTIALS",
        "message": "Invalid email or password"
    }
}
Status Description
400 Invalid credentials
429 Too many login attempts
POST /api/auth/refresh-token

Get new access token using refresh token.

Request Parameters
Parameter Type Description
refreshTokenrequired string Valid refresh token
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/refresh-token \
-H "Content-Type: application/json" \
-d {
    "refreshToken": "eyJhbG..."
}
Success Response (200 OK)
{
    "success": true,
    "tokens": {
        "accessToken": "eyJhbG...",
        "refreshToken": "eyJhbG..."
    }
}
Error Responses
{
    "success": false,
    "error": {
        "code": "INVALID_TOKEN",
        "message": "Invalid or expired refresh token"
    }
}
Status Description
401 Invalid or expired refresh token
POST /api/auth/verify-otp

Verify One-Time Password (OTP) for account verification.

Security

Maximum attempts: 3
OTP expires in: 10 minutes
Rate limited: 3 attempts per 15 minutes

Request Parameters
Parameter Type Description
_idrequired string User ID received during registration
otprequired string 6-digit verification code
verificationMethodrequired string "email" or "phone"
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/verify-otp \
-H "Content-Type: application/json" \
-d {
    "_id": "5f9d88b...",
    "otp": "123456",
    "verificationMethod": "email"
}
Success Response (200 OK)
{
    "success": true,
    "message": "OTP verified successfully",
    "user": {
        "id": "5f9d88b...",
        "email": "user@example.com",
        "isVerified": true
    },
    "tokens": {
        "accessToken": "eyJhbG...",
        "refreshToken": "eyJhbG..."
    }
}
Error Responses
{
    "success": false,
    "error": {
        "code": "INVALID_OTP",
        "message": "Invalid or expired OTP code"
    }
}
Status Description
400 Invalid or expired OTP
429 Too many verification attempts
POST /api/auth/2fa/generate

Generate Two-Factor Authentication (2FA) secret for user.

Authentication Required

This endpoint requires a valid access token.

Headers
Header Value
Authorization Bearer {accessToken}
Success Response
{
    "success": true,
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCode": "data:image/png;base64,...",
    "message": "Scan the QR code with your authenticator app"
}
POST /api/auth/2fa/verify

Verify 2FA code and enable two-factor authentication.

Authentication Required

This endpoint requires a valid access token.

Headers
Header Value
Authorization Bearer {accessToken}
Request Parameters
Parameter Type Description
coderequired string 6-digit 2FA code from authenticator app
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/2fa/verify \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d {
    "code": "123456"
}
Success Response
{
    "success": true,
    "message": "2FA enabled successfully",
    "backupCodes": [
        "1234-5678",
        "2345-6789",
        "3456-7890"
    ]
}
Error Responses
Status Description
400 Invalid 2FA code
401 Unauthorized - Invalid or expired token
429 Too many verification attempts
POST /api/auth/2fa/disable

Disable two-factor authentication for the user account.

Authentication Required

This endpoint requires a valid access token.

Headers
Header Value
Authorization Bearer {accessToken}
Request Parameters
Parameter Type Description
currentPasswordrequired string User's current password for verification
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/2fa/disable \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d {
    "currentPassword": "SecureP@ss123"
}
Success Response
{
    "success": true,
    "message": "2FA disabled successfully"
}
Error Responses
Status Description
400 Invalid password
401 Unauthorized - Invalid or expired token
POST /api/auth/forgot-password

Request a password reset link.

Rate Limited

Maximum 3 requests per hour per email address.

Request Parameters
Parameter Type Description
emailrequired string Registered email address
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/forgot-password \
-H "Content-Type: application/json" \
-d {
    "email": "user@example.com"
}
Success Response
{
    "success": true,
    "message": "If an account exists with this email, password reset instructions have been sent"
}
POST /api/auth/logout

Log out the current user session.

Authentication Required - Requires valid access token
Headers
Header Value
Authorization Bearer {accessToken}
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/logout \
-H "Authorization: Bearer {accessToken}"
Success Response (200 OK)
{
    "success": true,
    "message": "Successfully logged out"
}
Error Response
{
    "success": false,
    "error": "Invalid or expired token"
}
POST /api/auth/logout-all

Log out of all active sessions across devices.

Authentication Required - Requires valid access token
Headers
Header Value
Authorization Bearer {accessToken}
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/logout-all \
-H "Authorization: Bearer {accessToken}"
Success Response (200 OK)
{
    "success": true,
    "message": "Successfully logged out from all devices",
    "sessionsTerminated": 3
}
GET /api/auth/sessions

Get a list of all active sessions for the current user.

Authentication Required - Requires valid access token
Headers
Header Value
Authorization Bearer {accessToken}
Example Request
curl -X GET https://my-profile-server-api.onrender.com/api/auth/sessions \
-H "Authorization: Bearer {accessToken}"
Success Response (200 OK)
{
    "success": true,
    "sessions": [
        {
            "id": "sess_123",
            "device": "Chrome on Windows",
            "ip": "192.168.1.1",
            "location": "Paris, France",
            "lastActive": "2024-03-21T20:15:30Z",
            "current": true
        },
        {
            "id": "sess_456",
            "device": "iPhone 12",
            "ip": "192.168.1.2",
            "location": "London, UK",
            "lastActive": "2024-03-21T19:30:00Z",
            "current": false
        }
    ]
}
POST /api/auth/verify-email

Verify user's email address using verification token.

Request Parameters
Parameter Type Description
tokenrequired string Email verification token received in email
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/verify-email \
-H "Content-Type: application/json" \
-d {
    "token": "eyJhbG..."
}
Success Response (200 OK)
{
    "success": true,
    "message": "Email verified successfully"
}
Error Response
{
    "success": false,
    "error": "Invalid or expired verification token"
}
POST /api/auth/resend-otp

Request a new OTP code if the previous one expired.

Request Parameters
Parameter Type Description
emailrequired string Email address to send OTP to
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/resend-otp \
-H "Content-Type: application/json" \
-d {
    "email": "user@example.com"
}
Success Response (200 OK)
{
    "success": true,
    "message": "New OTP has been sent"
}
POST /api/auth/resend-verification

Request a new verification email if the previous one expired.

Request Parameters
Parameter Type Description
emailrequired string Email address to resend verification to
Example Request
curl -X POST https://my-profile-server-api.onrender.com/api/auth/resend-verification \
-H "Content-Type: application/json" \
-d {
    "email": "user@example.com"
}
Success Response (200 OK)
{
    "success": true,
    "message": "Verification email has been sent"
}
POST /api/auth/reset-password

Reset password using reset token.

Request Parameters
Parameter Type Description
tokenrequired string Reset token from email
passwordrequired string New password (must meet password requirements)
Example Request
curl -X POST https://api.myprofile.ltd/api/auth/reset-password \
-H "Content-Type: application/json" \
-d {
    "token": "eyJhbG...",
    "password": "NewSecureP@ss123"
}
Success Response
{
    "success": true,
    "message": "Password reset successful"
}
Error Responses
Status Description
400 Invalid or expired reset token
400 Password does not meet requirements